[ { "path": ".gitignore", "content": "# macOS system files\n.DS_Store\n\n# Python bytecode files\n__pycache__/\n*.pyc\n" }, { "path": "README.md", "content": "# Agent Skills\n\nAgent Skills are folders of instructions, scripts, and resources that AI agents can discover and use to perform at specific tasks. Write once, use everywhere.\n\nCodex uses skills to help package capabilities that teams and individuals can use to complete specific tasks in a repeatable way. This repository catalogs skills for use and distribution with Codex.\n\nLearn more:\n- [Using skills in Codex](https://developers.openai.com/codex/skills)\n- [Create custom skills in Codex](https://developers.openai.com/codex/skills/create-skill)\n- [Agent Skills open standard](https://agentskills.io)\n\n## Installing a skill\n\nSkills in [`.system`](skills/.system/) are automatically installed in the latest version of Codex.\n\nTo install [curated](skills/.curated/) or [experimental](skills/.experimental/) skills, you can use the `$skill-installer` inside Codex.\n\nCurated skills can be installed by name (defaults to `skills/.curated`):\n\n```\n$skill-installer gh-address-comments\n```\n\nFor experimental skills, specify the skill folder. For example:\n\n```\n$skill-installer install the create-plan skill from the .experimental folder\n```\n\nOr provide the GitHub directory URL:\n\n```\n$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan\n```\n\nAfter installing a skill, restart Codex to pick up new skills.\n\n## License\n\nThe license of an individual skill can be found directly inside the skill's directory inside the `LICENSE.txt` file.\n" }, { "path": "contributing.md", "content": "## Contributing\n\n### Community values\n\n- **Be kind and inclusive.** Treat others with respect; we follow the [Contributor Covenant](https://www.contributor-covenant.org/).\n- **Assume good intent.** Written communication is hard - err on the side of generosity.\n- **Teach & learn.** If you spot something confusing, open an issue or PR with improvements.\n\n### Security & responsible AI\n\nHave you discovered a vulnerability or have concerns about model output? Please e-mail **security@openai.com** and we will respond promptly.\n" }, { "path": "skills/.curated/aspnet-core/LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "skills/.curated/aspnet-core/SKILL.md", "content": "---\nname: aspnet-core\ndescription: Build, review, refactor, or architect ASP.NET Core web applications using current official guidance for .NET web development. Use when working on Blazor Web Apps, Razor Pages, MVC, Minimal APIs, controller-based Web APIs, SignalR, gRPC, middleware, dependency injection, configuration, authentication, authorization, testing, performance, deployment, or ASP.NET Core upgrades.\n---\n\n# ASP.NET Core\n\n## Overview\n\nChoose the right ASP.NET Core application model, compose the host and request pipeline correctly, and implement features in the framework style Microsoft documents today.\n\nLoad the smallest set of references that fits the task. Do not load every reference by default.\n\n## Workflow\n\n1. Confirm the target framework, SDK, and current app model.\n2. Open [references/stack-selection.md](references/stack-selection.md) first for new apps or major refactors.\n3. Open [references/program-and-pipeline.md](references/program-and-pipeline.md) next for `Program.cs`, DI, configuration, middleware, routing, logging, and static assets.\n4. Open exactly one primary app-model reference:\n - [references/ui-blazor.md](references/ui-blazor.md)\n - [references/ui-razor-pages.md](references/ui-razor-pages.md)\n - [references/ui-mvc.md](references/ui-mvc.md)\n - [references/apis-minimal-and-controllers.md](references/apis-minimal-and-controllers.md)\n5. Add cross-cutting references only as needed:\n - [references/data-state-and-services.md](references/data-state-and-services.md)\n - [references/security-and-identity.md](references/security-and-identity.md)\n - [references/realtime-grpc-and-background-work.md](references/realtime-grpc-and-background-work.md)\n - [references/testing-performance-and-operations.md](references/testing-performance-and-operations.md)\n6. Open [references/versioning-and-upgrades.md](references/versioning-and-upgrades.md) before introducing new platform APIs into an older solution or when migrating between major versions.\n7. Use [references/source-map.md](references/source-map.md) when you need the Microsoft Learn section that corresponds to a task not already covered by the focused references.\n\n## Default Operating Assumptions\n\n- Prefer the latest stable ASP.NET Core and .NET unless the repository or user request pins an older target.\n- As of March 2026, prefer .NET 10 / ASP.NET Core 10 for new production work. Treat ASP.NET Core 11 as preview unless the user explicitly asks for preview features.\n- Prefer `WebApplicationBuilder` and `WebApplication`. Avoid older `Startup` and `WebHost` patterns unless the codebase already uses them or the task is migration.\n- Prefer built-in DI, options/configuration, logging, ProblemDetails, OpenAPI, health checks, rate limiting, output caching, and Identity before adding third-party infrastructure.\n- Keep feature slices cohesive so the page, component, endpoint, controller, validation, service, data access, and tests are easy to trace.\n- Respect the existing app model. Do not rewrite Razor Pages to MVC or controllers to Minimal APIs without a clear reason.\n\n## Reference Guide\n\n- [references/_sections.md](references/_sections.md): Quick index and reading order.\n- [references/stack-selection.md](references/stack-selection.md): Choose the right ASP.NET Core application model and template.\n- [references/program-and-pipeline.md](references/program-and-pipeline.md): Structure `Program.cs`, services, middleware, routing, configuration, logging, and static assets.\n- [references/ui-blazor.md](references/ui-blazor.md): Build Blazor Web Apps, choose render modes, and use components, forms, and JS interop correctly.\n- [references/ui-razor-pages.md](references/ui-razor-pages.md): Build page-focused server-rendered apps with handlers, model binding, and conventions.\n- [references/ui-mvc.md](references/ui-mvc.md): Build controller/view applications with clear separation of concerns.\n- [references/apis-minimal-and-controllers.md](references/apis-minimal-and-controllers.md): Build HTTP APIs with Minimal APIs or controllers, including validation and response patterns.\n- [references/data-state-and-services.md](references/data-state-and-services.md): Use EF Core, `DbContext`, options, `IHttpClientFactory`, session, temp data, and app state responsibly.\n- [references/security-and-identity.md](references/security-and-identity.md): Apply authentication, authorization, Identity, secrets, data protection, CORS, CSRF, and HTTPS guidance.\n- [references/realtime-grpc-and-background-work.md](references/realtime-grpc-and-background-work.md): Use SignalR, gRPC, and hosted services.\n- [references/testing-performance-and-operations.md](references/testing-performance-and-operations.md): Add integration tests, browser tests, caching, compression, health checks, rate limits, and deployment concerns.\n- [references/versioning-and-upgrades.md](references/versioning-and-upgrades.md): Handle target frameworks, breaking changes, obsolete APIs, and migrations.\n- [references/source-map.md](references/source-map.md): Map the official ASP.NET Core documentation tree to the references in this skill.\n\n## Execution Notes\n\n- When generating new code, start from the correct `dotnet new` template and keep the generated structure recognizable.\n- When editing an existing solution, follow the solution's conventions first and use these references to avoid framework misuse or outdated patterns.\n- When a task mentions \"latest\", verify the feature on Microsoft Learn or the ASP.NET Core docs repo before relying on memory.\n" }, { "path": "skills/.curated/aspnet-core/agents/openai.yaml", "content": "interface:\n display_name: \"ASP.NET Core\"\n short_description: \"[Windows only] Build and review ASP.NET Core web apps\"\n icon_large: \"./assets/dotnet-logo.png\"\n default_prompt: \"Create a new $aspnet-core website for me.\"\n" }, { "path": "skills/.curated/aspnet-core/references/_sections.md", "content": "# Reference Sections\n\nUse this file as the routing table for the rest of the skill.\n\n## Start Here\n\n- New app or major redesign: `stack-selection.md` -> `program-and-pipeline.md` -> one primary app-model reference -> `security-and-identity.md` -> `testing-performance-and-operations.md`\n- Existing app feature work: primary app-model reference -> `program-and-pipeline.md` -> any needed cross-cutting references\n- API-first work: `apis-minimal-and-controllers.md` -> `security-and-identity.md` -> `data-state-and-services.md` -> `testing-performance-and-operations.md`\n- Authentication, authorization, or secrets: `security-and-identity.md`\n- Realtime, streaming, or background processing: `realtime-grpc-and-background-work.md`\n- Upgrade or migration work: `versioning-and-upgrades.md`\n\n## Primary References\n\n| File | Open when |\n| --- | --- |\n| `stack-selection.md` | Choose Blazor, Razor Pages, MVC, Minimal APIs, controllers, SignalR, or gRPC |\n| `program-and-pipeline.md` | Structure `Program.cs`, services, configuration, middleware, routing, logging, static files, and app startup |\n| `ui-blazor.md` | Build or review Blazor Web Apps and component-based UI |\n| `ui-razor-pages.md` | Build or review page-focused server-rendered applications |\n| `ui-mvc.md` | Build or review controller/view applications |\n| `apis-minimal-and-controllers.md` | Build or review HTTP APIs |\n\n## Cross-Cutting References\n\n| File | Open when |\n| --- | --- |\n| `data-state-and-services.md` | Register services, use EF Core, handle options/configuration, or manage app state |\n| `security-and-identity.md` | Add Identity, cookies, bearer auth, policies, CORS, CSRF, HTTPS, or secrets handling |\n| `realtime-grpc-and-background-work.md` | Add SignalR, gRPC, streaming, or hosted services |\n| `testing-performance-and-operations.md` | Add tests, caching, compression, health checks, rate limits, deployment, or proxy configuration |\n| `versioning-and-upgrades.md` | Migrate across ASP.NET Core versions, avoid obsolete APIs, or target preview features deliberately |\n| `source-map.md` | Map a task to the official ASP.NET Core documentation tree |\n\n## Reading Strategy\n\n- Open one app-model reference at a time unless the codebase genuinely mixes models.\n- Prefer the framework's built-in abstractions first.\n- Check `versioning-and-upgrades.md` before introducing APIs that might not exist in the repository's target framework.\n" }, { "path": "skills/.curated/aspnet-core/references/apis-minimal-and-controllers.md", "content": "# APIs: Minimal And Controllers\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis\n- https://learn.microsoft.com/aspnet/core/web-api/\n- https://learn.microsoft.com/aspnet/core/fundamentals/error-handling-api\n\n## First Decision\n\nChoose between:\n\n- Minimal APIs for focused, low-ceremony HTTP endpoints\n- controller-based APIs for richer MVC conventions and attribute-driven behavior\n\nDo not mix both styles in the same feature unless that split is genuinely useful.\n\n## Minimal API Guidance\n\nPrefer Minimal APIs when the surface is small to medium and you want concise endpoint definitions.\n\nGood defaults:\n\n- organize endpoints with route groups\n- keep route handlers thin\n- move business logic into services\n- prefer `TypedResults` over untyped results\n- use endpoint filters when cross-cutting behavior belongs at the endpoint layer\n- use built-in validation support on supported target frameworks\n\nMinimal API reminders:\n\n- handler parameters can be bound from route, query, headers, body, form, or DI\n- authorization can be applied with `RequireAuthorization`\n- return `IResult` or `TypedResults` when response shape matters\n- use OpenAPI support for discoverable contracts\n\nOn .NET 10, Minimal APIs support built-in validation with `AddValidation()`. Use that instead of inventing parallel validation infrastructure when the target framework supports it.\n\n## Controller API Guidance\n\nPrefer controllers when the API needs:\n\n- `[ApiController]` behaviors\n- attribute routing and conventions\n- filters\n- custom formatters\n- mature controller organization in an existing codebase\n\nController defaults:\n\n- derive API controllers from `ControllerBase`\n- annotate with `[ApiController]`\n- use attribute routing\n- return ProblemDetails-compatible failures\n- let automatic model validation handle invalid requests unless there is a concrete override requirement\n\nKey `[ApiController]` behaviors:\n\n- attribute routing is required\n- invalid model state automatically becomes HTTP 400\n- binding source inference applies\n- error responses use ProblemDetails patterns\n\n## Shared API Practices\n\n- Keep request and response DTOs separate from persistence models\n- Use version-stable route and payload contracts\n- Use `CreatedAt...` patterns for resource creation\n- Prefer explicit status codes and typed results over implicit behavior\n- Apply authorization at the endpoint or controller boundary, not only inside service methods\n- Use `ProblemDetails` for errors instead of ad hoc JSON shapes\n\n## Browser-Facing Notes\n\n- Be careful with cookie-authenticated API endpoints and CORS\n- For browser-based form or file upload endpoints, account for antiforgery requirements\n- In ASP.NET Core 10, known API endpoints no longer use cookie-login redirects by default; rely on API-appropriate unauthorized responses instead\n\n## Native AOT\n\nUse `dotnet new webapiaot` only when native AOT is an explicit deployment requirement. Treat it as a constraint that affects library choice, reflection, JSON patterns, and compatibility.\n" }, { "path": "skills/.curated/aspnet-core/references/data-state-and-services.md", "content": "# Data, State, And Services\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/data/\n- https://learn.microsoft.com/aspnet/core/fundamentals/dependency-injection\n- https://learn.microsoft.com/aspnet/core/fundamentals/http-requests\n- https://learn.microsoft.com/aspnet/core/fundamentals/app-state\n\n## Dependency Injection Defaults\n\n- Register infrastructure and business services in `Program.cs`\n- Inject dependencies through constructors by default\n- Keep scoped services request-bound\n- Avoid resolving scoped services from singletons\n- Use keyed or named patterns only when there is a real need for multiple implementations\n\n## EF Core And DbContext\n\nUse EF Core for common relational data access patterns unless the repository already uses another data layer.\n\nDefault guidance:\n\n- register `DbContext` with `AddDbContext`\n- treat `DbContext` as scoped\n- keep queries and transactions in services, not UI code\n- use migrations intentionally\n- keep entities out of public API contracts and UI view models\n\nUse `IDbContextFactory` when the execution model is not request-scoped, such as:\n\n- Blazor components with longer-lived scopes\n- background services\n- explicit factory-driven data work\n\n## Options And Configuration\n\n- Bind structured configuration into options classes\n- validate options early when bad configuration should fail fast\n- keep configuration access close to the service that owns it\n- avoid scattering raw configuration keys across the codebase\n\n## Outbound HTTP\n\nUse `IHttpClientFactory` for outbound HTTP calls.\n\nPrefer:\n\n- named clients for distinct external systems\n- typed clients for richer integrations\n- delegating handlers for retries, headers, or telemetry concerns\n\nAvoid manual `new HttpClient()` patterns scattered through request handlers.\n\n## App State\n\nUse the smallest state mechanism that fits:\n\n- query string or route values for transparent request state\n- form posts for user input\n- TempData for short-lived redirect-friendly messages\n- session only when necessary and with an understanding of its server-side and scaling implications\n\nDo not treat session as the primary application data store.\n\n## Caching And State Boundaries\n\n- Keep cached data derivable from a durable source\n- Separate cache shape from persistence shape when it improves safety or performance\n- Revisit session, in-memory cache, and singleton state when the app scales to multiple instances\n" }, { "path": "skills/.curated/aspnet-core/references/program-and-pipeline.md", "content": "# Program And Pipeline\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/fundamentals/\n- https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/webapplication\n- https://learn.microsoft.com/aspnet/core/fundamentals/middleware/\n- https://learn.microsoft.com/aspnet/core/fundamentals/configuration/\n\n## Startup Shape\n\nPrefer the modern hosting model:\n\n1. Create `var builder = WebApplication.CreateBuilder(args);`\n2. Register services on `builder.Services`\n3. Build `var app = builder.Build();`\n4. Configure middleware in the correct order\n5. Map endpoints\n6. Call `app.Run();`\n\nUse older `Startup` patterns only when the repository already uses them or the task is migration.\n\n## Service Registration\n\n- Register framework services explicitly: Razor Pages, controllers, Razor components, authentication, authorization, health checks, rate limiting, response compression, output caching, EF Core, and `IHttpClientFactory`\n- Keep business logic in services instead of controllers, page models, or route handlers\n- Use constructor injection as the default\n- Use options classes for structured configuration\n- Choose lifetimes intentionally:\n - singleton: stateless or shared infrastructure\n - scoped: request-bound work such as `DbContext`\n - transient: lightweight stateless services\n\n## Configuration Defaults\n\n`WebApplication.CreateBuilder` already loads configuration from common providers such as:\n\n- `appsettings.json`\n- environment-specific `appsettings.{Environment}.json`\n- environment variables\n- command-line arguments\n\nFor secrets:\n\n- use Secret Manager in development\n- use a secure external store in production\n- do not commit secrets to source control\n\n## Middleware Order\n\nMiddleware order is a frequent source of broken behavior. Favor this shape and adjust only with a concrete reason:\n\n1. Forwarded headers if behind a proxy or load balancer\n2. Exception handling and HSTS for non-development environments\n3. HTTPS redirection\n4. Static files\n5. Routing when explicit routing middleware is needed\n6. CORS when endpoints require it\n7. Authentication\n8. Authorization\n9. Endpoint-specific middleware such as rate limiting or session as required\n10. Endpoint mapping with `MapRazorPages`, `MapControllers`, `MapGet`, `MapHub`, or `MapGrpcService`\n\nImportant ordering rules:\n\n- Call `UseAuthentication()` before `UseAuthorization()`\n- Keep proxy/header processing before auth, redirects, and link generation\n- Do not insert custom middleware randomly between auth and authorization without a reason\n- In Minimal API apps, explicit `UseRouting()` is usually unnecessary unless you need to control order\n\n## Routing And Endpoints\n\n- Prefer endpoint routing everywhere\n- Use route groups for larger Minimal API surfaces\n- Keep MVC and API routes explicit and predictable\n- Use areas only when the application is large enough to benefit from bounded sections\n- Keep endpoint names stable when generating links or integrating with clients\n\n## Error Handling\n\n- Use centralized exception handling instead of scattered `try/catch` blocks for ordinary request failures\n- Prefer ProblemDetails-style responses for APIs\n- Keep the developer exception page limited to development\n- Separate user-facing failures from internal exception details\n\n## Logging And Diagnostics\n\n- Use `ILogger` from DI\n- Log structured values, not concatenated strings\n- Put correlation and request diagnostics in middleware or infrastructure, not business logic\n- Enable HTTP logging only when the scenario warrants it and avoid leaking sensitive data\n\n## Static Assets And Web Root\n\n- Keep public assets in `wwwroot`\n- Treat the web root as publicly readable content\n- Prevent publishing local-only static content through project file rules when needed\n- Use Razor Class Libraries for reusable UI assets across apps\n\n## Architectural Defaults\n\n- Keep `Program.cs` readable; extract feature registration to extension methods when it starts accumulating unrelated concerns\n- Prefer vertical slices or feature folders over giant \"Controllers\", \"Services\", and \"Repositories\" buckets with weak boundaries\n- Keep framework configuration close to the host and business logic out of it\n" }, { "path": "skills/.curated/aspnet-core/references/realtime-grpc-and-background-work.md", "content": "# Realtime, gRPC, And Background Work\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/signalr/introduction\n- https://learn.microsoft.com/aspnet/core/grpc/\n- https://learn.microsoft.com/aspnet/core/fundamentals/host/hosted-services\n\n## SignalR\n\nUse SignalR when the server must push updates to connected clients in near real time.\n\nGood fits:\n\n- chat\n- dashboards\n- notifications\n- collaborative editing\n- live status streams\n\nGuidance:\n\n- model the hub as a communication boundary, not the home of business logic\n- use groups and user targeting deliberately\n- authenticate connections when data is user-specific\n- plan for scale-out if the app may run on multiple instances\n\nRemember that Blazor interactive server rendering already relies on a real-time connection. Do not add a second realtime channel unless the feature truly needs one.\n\n## gRPC\n\nUse gRPC for efficient service-to-service communication, strongly typed contracts, and streaming over HTTP/2.\n\nPrefer gRPC when:\n\n- both ends are under your control\n- performance and contract fidelity matter\n- streaming is a first-class requirement\n\nGuidance:\n\n- keep `.proto` contracts versioned and stable\n- generate client and server types from contracts\n- keep auth, logging, and DI integrated with the host\n- account for browser interoperability differences before choosing gRPC for public browser clients\n\n## Background Work\n\nUse `IHostedService` or `BackgroundService` for in-process background tasks tied to the application host.\n\nDefaults:\n\n- keep background services small and observable\n- create scopes for scoped dependencies\n- do not capture scoped services directly in singleton hosted services\n- respect cancellation tokens\n- avoid long blocking startup paths\n\nIf the work is durable, high-volume, or business-critical, consider whether it belongs in an out-of-process queue or worker instead of only inside the web host.\n" }, { "path": "skills/.curated/aspnet-core/references/security-and-identity.md", "content": "# Security And Identity\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/security/\n- https://learn.microsoft.com/aspnet/core/security/authentication/identity\n- https://learn.microsoft.com/aspnet/core/security/authorization/introduction\n\n## Security Defaults\n\n- Use the most secure authentication flow available\n- Keep secrets out of source code and plain configuration files\n- Use Secret Manager in development\n- Use a secure production secret store\n- Enforce HTTPS\n- Apply least privilege to users, services, and data access\n\n## Authentication And Authorization\n\nAuthentication answers who the user or caller is. Authorization answers what they can do.\n\nDefault pipeline order:\n\n1. `UseAuthentication()`\n2. `UseAuthorization()`\n\nApply authorization at boundaries:\n\n- `[Authorize]` on controllers, actions, page models, or hubs\n- `RequireAuthorization()` on endpoints and route groups\n- policies for reusable rules\n- roles only when role-based checks are actually the right abstraction\n\nUse `AllowAnonymous` sparingly and intentionally.\n\n## Identity\n\nUse ASP.NET Core Identity when the app needs first-party user accounts, login flows, password management, email confirmation, MFA, or related account management.\n\nUseful starting points:\n\n- `dotnet new webapp -au Individual`\n- `dotnet new mvc -au Individual`\n\nIdentity guidance:\n\n- scaffold only the pages you truly need to customize\n- keep Identity UI updates maintainable; full scaffolding increases merge and upgrade cost\n- use policies and claims for authorization rather than encoding all decisions in page logic\n- persist data-protection keys appropriately in multi-instance deployments\n\nOn ASP.NET Core 10, Identity metrics are available for observing auth-related behavior. Use them when the app has meaningful authentication traffic or security monitoring requirements.\n\n## CSRF, CORS, And Browser Security\n\n- Use antiforgery protection for cookie-based interactive apps and form posts\n- Do not confuse CORS with authentication or authorization\n- Avoid permissive `AllowAnyOrigin` plus credentials combinations\n- Treat browser-side state as untrusted\n\n## HTTPS, HSTS, And Forwarded Headers\n\n- redirect HTTP to HTTPS\n- enable HSTS outside development when appropriate\n- configure forwarded headers correctly when behind proxies or load balancers\n- do not generate links or evaluate scheme-sensitive behavior before proxy headers are processed\n\n## Data Protection And Secrets\n\n- persist data-protection keys outside ephemeral local storage when the app runs on multiple instances\n- do not use environment variables as the preferred long-term home for production secrets when a stronger secret store is available\n- never check production credentials into source control\n\n## Blazor Note\n\nFor Blazor apps, read the general ASP.NET Core security guidance first and then the Blazor-specific security docs. Some Blazor security guidance adds to or supersedes the general guidance.\n" }, { "path": "skills/.curated/aspnet-core/references/source-map.md", "content": "# ASP.NET Core Source Map\n\nThis skill is synthesized from the official ASP.NET Core documentation tree and overview pages. Use this file to map a task to the corresponding Microsoft Learn area before opening deeper docs.\n\nCore sources:\n\n- https://learn.microsoft.com/aspnet/core/\n- https://raw.githubusercontent.com/dotnet/AspNetCore.Docs/main/aspnetcore/toc.yml\n- https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore\n\n## Documentation Tree Mapping\n\n| ASP.NET Core docs area | Use this skill reference first |\n| --- | --- |\n| Overview, Get started, What's new | `stack-selection.md`, `versioning-and-upgrades.md` |\n| Fundamentals | `program-and-pipeline.md` |\n| Web apps | `ui-blazor.md`, `ui-razor-pages.md`, `ui-mvc.md` |\n| APIs | `apis-minimal-and-controllers.md` |\n| Real-time apps | `realtime-grpc-and-background-work.md` |\n| Remote Procedure Call apps | `realtime-grpc-and-background-work.md` |\n| Servers, Host and deploy | `testing-performance-and-operations.md` |\n| Test, Debug, Troubleshoot | `testing-performance-and-operations.md` |\n| Data access | `data-state-and-services.md` |\n| Security and Identity | `security-and-identity.md` |\n| Performance | `testing-performance-and-operations.md` |\n| Migration and updates | `versioning-and-upgrades.md` |\n\n## Areas To Consult Directly On Microsoft Learn\n\nThe following topics are part of the ASP.NET Core documentation tree but are not expanded into their own dedicated reference file here:\n\n- globalization and localization\n- advanced hosting and YARP details\n- debugger and diagnostics tooling specifics\n- narrow API-reference pages for individual types\n\nWhen a task is dominated by one of those areas, go straight to the matching Microsoft Learn section after checking the reference files in this skill.\n\n## Practical Deep-Dive Rule\n\n- Start with the focused reference in this skill\n- If the task depends on a narrow platform detail, open the matching Learn article\n- If the task depends on version-specific behavior, confirm the correct moniker or breaking-changes page\n" }, { "path": "skills/.curated/aspnet-core/references/stack-selection.md", "content": "# Stack Selection\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/\n- https://learn.microsoft.com/aspnet/core/blazor/\n- https://learn.microsoft.com/aspnet/core/razor-pages/\n- https://learn.microsoft.com/aspnet/core/mvc/overview\n- https://learn.microsoft.com/aspnet/core/web-api/\n- https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis\n\n## Default Version Choice\n\n- Prefer the latest stable .NET and ASP.NET Core for new production work.\n- As of March 2026, that means `net10.0` unless the repository or user request says otherwise.\n- Treat ASP.NET Core 11 as preview. Do not adopt preview APIs by default.\n- If the repository already targets `net8.0`, `net9.0`, or another framework, stay within that target unless the task is explicitly an upgrade.\n\n## Template Short Names\n\nThe current .NET 10 SDK templates include:\n\n- `dotnet new blazor`\n- `dotnet new webapp`\n- `dotnet new mvc`\n- `dotnet new webapi`\n- `dotnet new webapiaot`\n- `dotnet new grpc`\n- `dotnet new web`\n- `dotnet new razorclasslib`\n\nVerify template names with `dotnet new list` if the environment differs.\n\n## Application Model Matrix\n\n| Model | Prefer when | Watch out for | Typical starting point |\n| --- | --- | --- | --- |\n| Blazor Web App | Build full-stack .NET UI with SSR plus optional interactivity | Interactive server needs a live connection; WebAssembly increases payload size | `dotnet new blazor` |\n| Razor Pages | Build page-focused CRUD, forms, dashboards, and line-of-business apps | Authorization cannot be applied per page handler; use MVC if handler-level control matters | `dotnet new webapp` |\n| MVC | Build large server-rendered apps with clear controller/view separation, filters, and action-based patterns | More ceremony than Razor Pages for simple page flows | `dotnet new mvc` |\n| Minimal APIs | Build focused HTTP APIs, internal services, lightweight backends, and small surface areas | Route handlers can become hard to manage if business logic or metadata grows without structure | `dotnet new webapi` or `dotnet new web` |\n| Controller-based Web API | Build APIs that benefit from `[ApiController]`, content negotiation, filters, formatters, and mature controller conventions | More ceremony than Minimal APIs for small endpoints | `dotnet new webapi` |\n| SignalR | Add server push, live updates, chat, collaborative UI, or notifications | Requires connection lifecycle management and scale-out planning | Add to an existing ASP.NET Core app |\n| gRPC | Build service-to-service or streaming RPC over HTTP/2 | Browser support is different from ordinary JSON APIs; use gRPC-Web only when needed | `dotnet new grpc` |\n\n## Fast Heuristics\n\n- Choose Blazor Web App when the UI itself should be a .NET component model.\n- Choose Razor Pages when the app is mostly page and form oriented.\n- Choose MVC when actions, views, filters, and controller conventions are the center of the design.\n- Choose Minimal APIs first for small to medium HTTP services.\n- Switch to controllers when the API needs richer attribute-driven behavior, custom formatters, or strong alignment with existing MVC/Web API conventions.\n- Keep the current app model in an existing codebase unless the mismatch is causing real complexity.\n\n## Mixed-Model Guidance\n\nASP.NET Core can mix models in one host. Common combinations:\n\n- Razor Pages or MVC for server-rendered UI plus Minimal APIs for AJAX or mobile endpoints\n- Blazor Web App plus Minimal APIs for external integration endpoints\n- MVC or Razor Pages plus SignalR for live updates\n- Web API plus gRPC for internal service-to-service calls\n\nMix models only when it simplifies the public surface. Do not add a second app model just because ASP.NET Core allows it.\n" }, { "path": "skills/.curated/aspnet-core/references/testing-performance-and-operations.md", "content": "# Testing, Performance, And Operations\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/test/integration-tests\n- https://learn.microsoft.com/aspnet/core/host-and-deploy/\n- https://learn.microsoft.com/aspnet/core/host-and-deploy/health-checks\n- https://learn.microsoft.com/aspnet/core/performance/\n\n## Testing Strategy\n\nUse layered testing instead of relying on one style:\n\n- unit tests for pure services and business logic\n- integration tests for request pipeline, DI, database, auth, and framework wiring\n- browser tests for end-to-end user flows\n\n## Integration Tests\n\nUse `Microsoft.AspNetCore.Mvc.Testing` and `WebApplicationFactory` for integration tests.\n\nGuidance from the official docs:\n\n- use a test host and `HttpClient`\n- replace services with test doubles when needed\n- control redirects when asserting auth behavior\n- handle antiforgery correctly for form posts\n- prefer SQLite in-memory over the EF Core in-memory provider for more realistic database tests\n\nFor SPA or browser-driven scenarios, Microsoft recommends browser automation such as Playwright for .NET.\n\n## Performance Defaults\n\nReach for built-in features before custom optimization layers:\n\n- output caching\n- response caching where appropriate\n- response compression\n- HTTP request timeouts\n- rate limiting\n- static file handling\n\nGeneral performance guidance:\n\n- measure first\n- keep database and network round trips visible\n- reduce payload size\n- use streaming or pagination when data is large\n- keep synchronous blocking out of hot paths\n\n## Health Checks And Observability\n\nAdd health checks for dependencies that matter operationally.\n\nUse separate checks or tags when you need:\n\n- liveness\n- readiness\n- dependency-specific health surfaces\n\nAlso ensure:\n\n- structured logs\n- request tracing where applicable\n- metrics for critical paths such as auth, API latency, and background work\n\n## Hosting And Deployment\n\nTypical deployment flow:\n\n1. `dotnet publish`\n2. deploy the publish output\n3. run behind a process manager\n4. place a reverse proxy in front when the environment requires it\n\nKnow the deployment environment:\n\n- IIS or Windows Service on Windows\n- Kestrel plus Nginx or another reverse proxy on Linux\n- container hosting when the platform expects it\n\nBehind proxies or load balancers:\n\n- configure forwarded headers\n- validate scheme, host, and remote IP behavior\n- test auth redirects and callback URLs in the deployed topology\n\n## Operational Safeguards\n\n- add health checks for databases and critical external services\n- fail fast on invalid configuration where possible\n- keep secrets out of publish artifacts\n- verify data-protection key persistence in multi-instance deployments\n" }, { "path": "skills/.curated/aspnet-core/references/ui-blazor.md", "content": "# Blazor\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/blazor/\n- https://learn.microsoft.com/aspnet/core/blazor/fundamentals/\n- https://learn.microsoft.com/aspnet/core/blazor/security/\n\n## Choose Blazor Deliberately\n\nPrefer Blazor when the UI itself should be built as reusable .NET components and the team wants a full-stack .NET model.\n\nCurrent guidance centers on the Blazor Web App model, which can combine:\n\n- static SSR for fast first render\n- interactive server rendering\n- interactive WebAssembly rendering\n- per-component render mode choices\n\nUse standalone Blazor WebAssembly only when the app is intentionally client-heavy or must run as static files without a server-rendered host.\n\n## Render Mode Heuristics\n\n- Start with static SSR when the page is mostly read-only and fast first paint matters\n- Use interactive server rendering when you want rich interactivity without shipping the full .NET runtime to the browser\n- Use interactive WebAssembly when offline capability, client-side execution, or browser-local compute is the point\n- Mix render modes only when the split is clear and justified\n\n## Component Patterns\n\n- Keep components focused and composable\n- Move data access and business rules into injected services\n- Pass data through parameters, not hidden global state\n- Use forms and validation with Blazor's built-in editing and validation components\n- Prefer shared Razor Class Libraries for reusable component sets\n\n## Data And Interactivity\n\n- Use DI in components with restraint; avoid turning components into service locators\n- Treat JS interop as an edge mechanism for browser APIs or third-party libraries, not the primary application model\n- Keep long-running work off the UI event path\n- Be deliberate about prerendering, streaming rendering, and enhanced navigation when they improve perceived performance\n\n## Security Notes\n\n- Follow the general ASP.NET Core security guidance first, then load the Blazor-specific docs for details that supersede it\n- Remember that client-side code and browser state are not trusted\n- Keep secrets and privileged operations on the server\n- Use authorization-aware UI only as a convenience layer; enforce rules on the server as well\n\n## When Not To Use Blazor\n\n- Do not force Blazor onto a mostly conventional server-rendered app that already fits Razor Pages or MVC well\n- Do not choose WebAssembly by default for small interaction needs that SSR or interactive server rendering handles more simply\n" }, { "path": "skills/.curated/aspnet-core/references/ui-mvc.md", "content": "# MVC\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/mvc/overview\n- https://learn.microsoft.com/aspnet/core/mvc/controllers/\n- https://learn.microsoft.com/aspnet/core/mvc/views/\n\n## Choose MVC When Actions And Views Matter\n\nPrefer MVC when the application benefits from explicit controllers, action-based routing, filters, view models, and a strong separation between orchestration and presentation.\n\nThis is often the right fit for:\n\n- large server-rendered sites\n- applications with many cross-cutting filters or action conventions\n- applications that mix views and APIs in the same controller layer\n- teams already organized around controllers and views\n\n## Core Shape\n\nEnable MVC with views using:\n\n- `builder.Services.AddControllersWithViews();`\n- `app.MapControllerRoute(...)`\n\nKeep views focused on presentation. Keep controllers focused on HTTP orchestration. Put business rules in services.\n\n## Controller Guidance\n\n- Derive from `Controller` when the controller returns views\n- Keep actions small and explicit\n- Use model binding and validation instead of manual request parsing\n- Return view models, not EF entities, to views\n- Use POST-Redirect-GET for form submissions\n\n## View Guidance\n\n- Use layouts, partial views, and Tag Helpers to keep markup consistent\n- Keep complex display logic out of Razor markup when it becomes hard to follow\n- Use strongly typed view models\n- Avoid coupling views directly to persistence models\n\n## Structure And Scale\n\n- Use areas for large bounded sections such as Admin or BackOffice\n- Keep route conventions explicit\n- Apply filters when behavior truly belongs at the MVC layer\n- Avoid giant god controllers; split by cohesive feature or resource\n\n## Choosing MVC Over Razor Pages\n\nPrefer MVC over Razor Pages when:\n\n- multiple related actions share controller-level behavior\n- handler-level authorization or action filters matter\n- URL and action design are more natural than page-file routing\n" }, { "path": "skills/.curated/aspnet-core/references/ui-razor-pages.md", "content": "# Razor Pages\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/razor-pages/\n- https://learn.microsoft.com/aspnet/core/tutorials/razor-pages/\n\n## Choose Razor Pages For Page-Centered Apps\n\nPrefer Razor Pages when requests naturally map to pages, forms, and page-level handlers. This is a strong default for internal tools, CRUD apps, account flows, and admin surfaces.\n\n## Core Shape\n\nEnable Razor Pages with:\n\n- `builder.Services.AddRazorPages();`\n- `app.MapRazorPages();`\n\nUse the `@page` directive to turn a `.cshtml` file into an endpoint. Keep request logic in the paired `PageModel` class when the page is more than trivial.\n\n## Routing Model\n\n- File system location defines the route by default\n- `Pages/Index.cshtml` maps to `/`\n- `Pages/Store/Index.cshtml` maps to `/Store`\n- Keep folder structure meaningful because it becomes the URL structure\n\n## PageModel Guidance\n\n- Use `OnGet`, `OnPost`, and named handlers for request processing\n- Use bindable properties and model validation for forms\n- Keep page models thin; move business logic into injected services\n- Use Tag Helpers and model binding instead of manual request parsing\n\n## Good Fits\n\n- form-heavy workflows\n- dashboards and back-office applications\n- simple content with server-side validation\n- applications where a page is the primary navigation unit\n\n## Key Limitation\n\nDo not rely on per-handler authorization with Razor Pages. Microsoft explicitly recommends using MVC controllers when different handlers on the same logical surface need different authorization behavior.\n\nPreferred responses to that limitation:\n\n- split the handlers into separate pages\n- move the surface to MVC if action-level authorization is a better fit\n\n## Organizational Guidance\n\n- Group related pages into folders\n- Use partial views for repeated fragments\n- Use areas only when the application has clear bounded sections\n- Keep shared layout and page conventions centralized\n" }, { "path": "skills/.curated/aspnet-core/references/versioning-and-upgrades.md", "content": "# Versioning And Upgrades\n\nPrimary docs:\n- https://learn.microsoft.com/aspnet/core/release-notes/\n- https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0\n- https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-9.0\n- https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/breaking-changes\n\n## Versioning Default\n\n- For new production apps in March 2026, prefer `net10.0`\n- For existing apps, match the repository's target framework unless the task is explicitly an upgrade\n- Before using a new API, confirm it exists in the target framework\n\n## Upgrade Workflow\n\n1. Identify the current target framework and SDK\n2. Read the \"What's new\" and breaking-changes pages for each version hop\n3. Compile and resolve obsoletions intentionally\n4. Re-run integration tests and auth flows\n5. Re-test deployment-specific behavior such as proxies, cookies, and static assets\n\n## High-Value Breaking-Change Checks\n\nWhen moving to ASP.NET Core 10, watch for:\n\n- cookie login redirects disabled for known API endpoints\n- `WithOpenApi` deprecation\n- `WebHostBuilder`, `IWebHost`, and `WebHost` obsolescence\n- Razor runtime compilation obsolescence\n\nWhen moving to ASP.NET Core 9, watch for:\n\n- `ValidateOnBuild` and `ValidateScopes` enabled in development when using `HostBuilder`\n- middleware constructor expectations and DI validation changes\n\nWhen moving to ASP.NET Core 8, watch for:\n\n- Minimal API `IFormFile` antiforgery requirements\n- `AddRateLimiter()` and `AddHttpLogging()` requirements when corresponding middleware is used\n\n## Migration Principles\n\n- Prefer migration to the modern hosting model when touching startup extensively\n- Remove compatibility shims only after tests confirm behavior\n- Avoid mixing new framework idioms with old startup architecture in a half-migrated state\n- Keep one authoritative target framework in project files unless multi-targeting is deliberate\n\n## Preview Feature Rule\n\nDo not introduce preview-only APIs or docs guidance unless the user explicitly asks for preview adoption or the repository is already on preview SDKs.\n" }, { "path": "skills/.curated/chatgpt-apps/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/chatgpt-apps/SKILL.md", "content": "---\nname: chatgpt-apps\ndescription: Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.\n---\n\n# ChatGPT Apps\n\n## Overview\n\nScaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.\n\nUse this skill to produce:\n\n- A primary app-archetype classification and repo-shape decision\n- A tool plan (names, schemas, annotations, outputs)\n- An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)\n- An MCP server scaffold (resource registration, tool handlers, metadata)\n- A widget scaffold (MCP Apps bridge first, `window.openai` compatibility/extensions second)\n- A reusable Node + `@modelcontextprotocol/ext-apps` starter scaffold for low-dependency fallbacks\n- A validation report against the minimum working repo contract\n- Local dev and connector setup steps\n- A short stakeholder summary of what the app does (when requested)\n\n## Mandatory Docs-First Workflow\n\nUse `$openai-docs` first whenever building or changing a ChatGPT Apps SDK app.\n\n1. Invoke `$openai-docs` (preferred) or call the OpenAI docs MCP server directly.\n2. Fetch current Apps SDK docs before writing code, especially (baseline pages):\n - `apps-sdk/build/mcp-server`\n - `apps-sdk/build/chatgpt-ui`\n - `apps-sdk/build/examples`\n - `apps-sdk/plan/tools`\n - `apps-sdk/reference`\n3. Fetch `apps-sdk/quickstart` when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.\n4. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:\n - `apps-sdk/deploy`\n - `apps-sdk/deploy/submission`\n - `apps-sdk/app-submission-guidelines`\n5. Cite the docs URLs you used when explaining design choices or generated scaffolds.\n6. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.\n7. If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.\n\nIf `$openai-docs` is unavailable, use:\n\n- `mcp__openaiDeveloperDocs__search_openai_docs`\n- `mcp__openaiDeveloperDocs__fetch_openai_doc`\n\nRead `references/apps-sdk-docs-workflow.md` for suggested doc queries and a compact checklist.\nRead `references/app-archetypes.md` to classify the request into a small number of supported app shapes before choosing examples or scaffolds.\nRead `references/repo-contract-and-validation.md` when generating or reviewing a repo so the output stays inside a stable “working app” contract.\nRead `references/search-fetch-standard.md` when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research.\nRead `references/upstream-example-workflow.md` when starting a greenfield app or when deciding whether to adapt an upstream example or use the local fallback scaffold.\nRead `references/window-openai-patterns.md` when the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific `app.*` helpers.\n\n## Prompt Guidance\n\nUse prompts that explicitly pair this skill with `$openai-docs` so the resulting scaffold is grounded in current docs.\n\nPreferred prompt patterns:\n\n- `Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for with a MCP server and widget.`\n- `Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for .`\n- `Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.`\n- `Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.`\n\nWhen responding, ask for or infer these inputs before coding:\n\n- Use case and primary user flows\n- Read-only vs mutating tools\n- Demo vs production target\n- Private/internal use vs public directory submission\n- Backend language and UI stack\n- Auth requirements\n- External API domains for CSP allowlists\n- Hosting target and local dev approach\n- Org ownership/verification readiness (for submission tasks)\n\n## Classify The App Before Choosing Code\n\nBefore choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it.\n\n- `tool-only`\n- `vanilla-widget`\n- `react-widget`\n- `interactive-decoupled`\n- `submission-ready`\n\nInfer the archetype unless a missing detail is truly blocking. Use the archetype to choose:\n\n- whether a UI is needed at all\n- whether to preserve a split `server/` + `web/` layout\n- whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold\n- which validation checks matter most\n- whether `search` and `fetch` should be the default read-only tool surface\n\nRead `references/app-archetypes.md` for the decision rubric.\n\n## Default Starting-Point Order\n\nFor greenfield apps, prefer these starting points in order:\n\n1. **Official OpenAI examples** when a close example already matches the requested stack or interaction pattern.\n2. **Version-matched `@modelcontextprotocol/ext-apps` examples** when the user needs a lower-level or more portable MCP Apps baseline.\n3. **`scripts/scaffold_node_ext_apps.mjs`** only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.\n\nDo not generate a large custom scaffold from scratch if a close upstream example already exists.\nCopy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.\n\n## Build Workflow\n\n### 0. Classify The App Archetype\n\nPick one primary archetype before planning tools or choosing a starting point.\n\n- Prefer a single primary archetype instead of mixing several.\n- If the request is broad, infer the smallest archetype that can still satisfy it.\n- Escalate to `submission-ready` only when the user asks for public launch, directory submission, or review-ready deployment.\n- Call out the chosen archetype in your response so the user can correct it early if needed.\n\n### 1. Plan Tools Before Code\n\nDefine the tool surface area from user intents.\n\n- Use one job per tool.\n- Write tool descriptions that start with \"Use this when...\" behavior cues.\n- Make inputs explicit and machine-friendly (enums, required fields, bounds).\n- Decide whether each tool is data-only, render-only, or both.\n- Set annotations accurately (`readOnlyHint`, `destructiveHint`, `openWorldHint`; add `idempotentHint` when true).\n- If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard `search` and `fetch` tools instead of inventing custom read-only equivalents.\n- For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.\n- Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.\n\nRead `references/search-fetch-standard.md` when `search` and `fetch` may be relevant.\n\n### 2. Choose an App Architecture\n\nChoose the simplest structure that fits the goal.\n\n- Use a **minimal demo pattern** for quick prototypes, workshops, or proofs of concept.\n- Use a **decoupled data/render pattern** for production UX so the widget does not re-render on every tool call.\n\nPrefer the decoupled pattern for non-trivial apps:\n\n- Data tools return reusable `structuredContent`.\n- Render tools attach `_meta.ui.resourceUri` and optional `_meta[\"openai/outputTemplate\"]`.\n- Render tool descriptions state prerequisites (for example, \"Call `search` first\").\n\n### 2a. Start From An Upstream Example When One Fits\n\nDefault to upstream examples for greenfield work when they are close to the requested app.\n\n- Check the official OpenAI examples first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.\n- Use `@modelcontextprotocol/ext-apps` examples when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.\n- Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.\n- After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations, `_meta.ui.*`, CSP, URI versioning, and local run instructions.\n- State which example you chose and why in one sentence.\n\nRead `references/upstream-example-workflow.md` for the selection and adaptation rubric.\n\n### 2b. Use the Starter Script When a Low-Dependency Fallback Helps\n\nUse `scripts/scaffold_node_ext_apps.mjs` only when the user wants a quick, greenfield Node starter and a vanilla HTML widget is acceptable, and no upstream example is a better starting point.\n\n- Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.\n- If you choose the script instead of an upstream example, say why the fallback is better for that request.\n- Skip it when a close official example exists, when the user already has an existing app structure, when they need a non-Node stack, when they explicitly want React first, or when they only want a plan/review instead of code.\n- The script generates a minimal `@modelcontextprotocol/ext-apps` server plus a vanilla HTML widget that uses the MCP Apps bridge by default.\n- The generated widget keeps follow-up messaging on the standard `ui/message` bridge and only uses `window.openai` for optional host signals/extensions.\n- After running it, patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.\n\n### 3. Scaffold the MCP Server\n\nGenerate a server that:\n\n- Registers a widget resource/template with the MCP Apps UI MIME type (`text/html;profile=mcp-app`) or the SDK constant (`RESOURCE_MIME_TYPE`) when using `@modelcontextprotocol/ext-apps/server`\n- Registers tools with clear names, schemas, titles, and descriptions\n- Returns `structuredContent` (model + widget), `content` (model narration), and `_meta` (widget-only data) intentionally\n- Keeps handlers idempotent or documents non-idempotent behavior explicitly\n- Includes tool status strings (`openai/toolInvocation/*`) when helpful in ChatGPT\n\nKeep `structuredContent` concise. Move large or sensitive widget-only payloads to `_meta`.\n\n### 4. Scaffold the Widget UI\n\nUse the MCP Apps bridge first for portability, then add ChatGPT-specific `window.openai` APIs when they materially improve UX.\n\n- Listen for `ui/notifications/tool-result` (JSON-RPC over `postMessage`)\n- Render from `structuredContent`\n- Use `tools/call` for component-initiated tool calls\n- Use `ui/update-model-context` only when UI state should change what the model sees\n\nUse `window.openai` for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.\n\n#### API Surface Guardrails\n\n- Some examples wrap the bridge with an `app` object (for example, `@modelcontextprotocol/ext-apps/react`) and expose helper names like `app.sendMessage()`, `app.callServerTool()`, `app.openLink()`, or host getter methods.\n- Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.\n- For ChatGPT-facing guidance, prefer the current documented surface: `window.openai.callTool(...)`, `window.openai.sendFollowUpMessage(...)`, `window.openai.openExternal(...)`, `window.openai.requestDisplayMode(...)`, and direct globals like `window.openai.theme`, `window.openai.locale`, `window.openai.displayMode`, `window.openai.toolInput`, `window.openai.toolOutput`, `window.openai.toolResponseMetadata`, and `window.openai.widgetState`.\n- If you reference wrapper helpers from repo examples, map them back to the documented `window.openai` or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.\n- Use `references/window-openai-patterns.md` for the wrapper-to-canonical mapping and for React helper extraction patterns.\n\n### 5. Add Resource Metadata and Security\n\nSet resource metadata deliberately on the widget resource/template:\n\n- `_meta.ui.csp` with exact `connectDomains` and `resourceDomains`\n- `_meta.ui.domain` for app submission-ready deployments\n- `_meta.ui.prefersBorder` (or OpenAI compatibility alias when needed)\n- Optional `openai/widgetDescription` to reduce redundant narration\n\nAvoid `frameDomains` unless iframe embeds are core to the product.\n\n### 5a. Enforce A Minimum Working Repo Contract\n\nEvery generated repo should satisfy a small, stable contract before you consider it done.\n\n- The repo shape matches the chosen archetype.\n- The MCP server and tools are wired to a reachable `/mcp` endpoint.\n- Tools have clear descriptions, accurate annotations, and UI metadata where needed.\n- Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard `search` and `fetch` tool shapes when relevant.\n- The widget uses the MCP Apps bridge correctly when a UI exists.\n- The repo includes enough scripts or commands for a user to run and check it locally.\n- The response explicitly says what validation was run and what was not run.\n\nRead `references/repo-contract-and-validation.md` for the detailed checklist and validation ladder.\n\n### 6. Validate the Local Loop\n\nValidate against the minimum working repo contract, not just “did files get created.”\n\n- Run the lowest-cost checks first:\n - static contract review\n - syntax or compile checks when feasible\n - local `/mcp` health check when feasible\n- Then move up to runtime checks:\n - verify tool descriptors and widget rendering in MCP Inspector\n - test the app in ChatGPT developer mode through HTTPS tunneling\n - exercise retries and repeated tool calls to confirm idempotent behavior\n - check widget updates after host events and follow-up tool calls\n- If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.\n\nRead `references/repo-contract-and-validation.md` for the validation ladder.\n\n### 7. Connect and Test in ChatGPT (Developer Mode)\n\nFor local development, include explicit ChatGPT setup steps (not just code/run commands).\n\n- Run the MCP server locally on `http://localhost:/mcp`\n- Expose the local server with a public HTTPS tunnel (for example `ngrok http `)\n- Use the tunneled HTTPS URL plus `/mcp` path when connecting from ChatGPT\n- In ChatGPT, enable Developer Mode under **Settings → Apps & Connectors → Advanced settings**\n- In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL\n- Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors\n\nNote: Some docs/screenshots still use older \"connector\" terminology. Prefer current product wording (\"app\") while acknowledging both labels when giving step-by-step instructions.\n\n### 8. Plan Production Hosting and Deployment\n\nWhen the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately).\n\n- Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS\n- Preserve low-latency streaming behavior on `/mcp`\n- Configure secrets outside the repo (environment variables / secret manager)\n- Add logging, request latency tracking, and error visibility for tool calls\n- Add basic observability (CPU, memory, request volume) and a troubleshooting path\n- Re-test the hosted endpoint in ChatGPT Developer Mode before submission\n\n### 9. Prepare Submission and Publish (Public Apps Only)\n\nOnly include these steps when the user intends a public directory listing.\n\n- Use `apps-sdk/deploy/submission` for the submission flow and `apps-sdk/app-submission-guidelines` for review requirements\n- Keep private/internal apps in Developer Mode instead of submitting\n- Confirm org verification and Owner-role prerequisites before submission work\n- Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured\n- Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info\n- If auth is required, include review-safe demo credentials and test the login path end-to-end\n- Submit for review in the Platform dashboard, monitor review status, and publish only after approval\n\n## Interactive State Guidance\n\nRead `references/interactive-state-sync-patterns.md` when the app has long-lived widget state, repeated interactions, or component-initiated tool calls (for example, games, boards, maps, dashboards, editors).\n\nUse it to choose patterns for:\n\n- State snapshots plus monotonic event tokens (`stateVersion`, `resetCount`, etc.)\n- Idempotent retry-safe handlers\n- `structuredContent` vs `_meta` partitioning\n- MCP Apps bridge-first update flows with optional `window.openai` compatibility\n- Decoupled data/render tool architecture for more complex interactive apps\n\n## Output Expectations\n\nWhen using this skill to scaffold code, produce output in this order unless the user asks otherwise:\n\n- For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.\n\n1. Primary app archetype chosen and why\n2. Tool plan and architecture choice (minimal vs decoupled)\n3. Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why\n4. Doc pages/URLs used from `$openai-docs`\n5. File tree to create or modify\n6. Implementation (server + widget)\n7. Validation performed against the minimum working repo contract\n8. Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)\n9. Deployment/hosting guidance (if requested or implied)\n10. Submission-readiness checklist (for public launch requests)\n11. Risks, gaps, and follow-up improvements\n\n## References\n\n- `references/app-archetypes.md` for classifying requests into a small number of supported app shapes\n- `references/apps-sdk-docs-workflow.md` for doc queries, page targets, and code-generation checklist\n- `references/interactive-state-sync-patterns.md` for reusable patterns for stateful or highly interactive widget apps\n- `references/repo-contract-and-validation.md` for the minimum working repo contract and lightweight validation ladder\n- `references/search-fetch-standard.md` for when and how to default to the standard `search` and `fetch` tools\n- `references/upstream-example-workflow.md` for choosing between official examples, ext-apps examples, and the local fallback scaffold\n- `references/window-openai-patterns.md` for ChatGPT-specific extensions, wrapper API translation, and React helper patterns\n- `scripts/scaffold_node_ext_apps.mjs` for a minimal Node + `@modelcontextprotocol/ext-apps` fallback starter scaffold\n" }, { "path": "skills/.curated/chatgpt-apps/agents/openai.yaml", "content": "interface:\n display_name: \"ChatGPT Apps\"\n short_description: \"Build and scaffold ChatGPT apps\"\n default_prompt: \"Use $chatgpt-apps to classify the app archetype first, fetch current OpenAI Apps SDK docs before generating code, default to the standard `search` and `fetch` tools when the app is connector-like or sync-oriented, adapt the closest upstream example when one fits, and only fall back to the local Node scaffold for minimal `@modelcontextprotocol/ext-apps` starters. Produce a working repo shape, then report what validation was actually run.\"\ndependencies:\n tools:\n - type: \"mcp\"\n value: \"openaiDeveloperDocs\"\n description: \"OpenAI developer docs MCP server for current Apps SDK guidance\"\n transport: \"streamable_http\"\n url: \"https://developers.openai.com/mcp\"\npolicy:\n allow_implicit_invocation: true\n" }, { "path": "skills/.curated/chatgpt-apps/references/app-archetypes.md", "content": "# App Archetypes\n\nLoad this reference before choosing a starting point for a new ChatGPT app. The goal is to keep the skill inside a small number of supported app shapes instead of inventing a custom structure for every prompt.\n\n## Rule\n\nChoose one primary archetype per request and state it.\n\nDo not combine several archetypes unless the user explicitly asks for a hybrid app and the extra complexity is necessary.\n\n## Archetypes\n\n### `tool-only`\n\nUse when:\n\n- The user does not need an in-ChatGPT UI\n- The task is mainly search, fetch, retrieval, or background actions\n\nDefault shape:\n\n- MCP server only\n\nBest starting point:\n\n- Official docs and MCP server examples\n\nValidation emphasis:\n\n- `/mcp` route works\n- tool schemas and annotations are correct\n- no unnecessary UI resource is registered\n- if the app is connector-like or sync-oriented, `search` and `fetch` should be the default read-only tools\n\n### `vanilla-widget`\n\nUse when:\n\n- The user wants a small demo, workshop starter, or simple inline widget\n- A single HTML widget is enough\n- The user wants the fastest path to a working repo\n\nDefault shape:\n\n- Root-level server plus `public/` widget assets\n\nBest starting point:\n\n- Apps SDK quickstart first\n- Local fallback scaffold if the quickstart is not a good fit\n\nValidation emphasis:\n\n- bridge initialization\n- `ui/notifications/tool-result`\n- `tools/call` only when the widget is interactive\n\n### `react-widget`\n\nUse when:\n\n- The user wants a polished UI\n- The UI is clearly component-based\n- The user mentions React, TypeScript frontend tooling, or richer design requirements\n\nDefault shape:\n\n- Split `server/` + `web/` layout when the example already uses it\n\nBest starting point:\n\n- Official OpenAI examples\n\nValidation emphasis:\n\n- build output is wired into the server correctly\n- bundle references resolve\n- widget renders from `structuredContent`\n\n### `interactive-decoupled`\n\nUse when:\n\n- The app has repeated user interaction\n- The widget should stay mounted while tools are called repeatedly\n- The app is a board, map, editor, game, dashboard, or other stateful experience\n\nDefault shape:\n\n- Split `server/` + `web/`\n- data tools plus render tools\n\nBest starting point:\n\n- Official OpenAI examples plus `references/interactive-state-sync-patterns.md`\n\nValidation emphasis:\n\n- tool retries are safe\n- widget does not remount unnecessarily\n- state sync is intentional\n- UI tool calls work independently of model reruns\n\n### `submission-ready`\n\nUse when:\n\n- The user asks for public launch, review readiness, or directory submission\n\nDefault shape:\n\n- Smallest viable repo that still includes deployment and review requirements\n\nBest starting point:\n\n- Closest official example that matches the requested stack\n\nValidation emphasis:\n\n- `_meta.ui.domain`\n- accurate CSP\n- auth and review-safe flows\n- submission prerequisites and artifacts\n\n## Selection Heuristic\n\n- If the prompt does not mention a UI, choose `tool-only`.\n- If the prompt is about a knowledge source, sync app, connector-like integration, or deep research, strongly prefer `tool-only` plus the standard `search` and `fetch` tools unless the user clearly needs a widget.\n- If the prompt asks for a simple demo or starter, choose `vanilla-widget`.\n- If the prompt asks for a polished UI or React, choose `react-widget`.\n- If the prompt implies long-lived client state or repeated interaction, choose `interactive-decoupled`.\n- Only choose `submission-ready` when the user explicitly asks for launch or review-readiness work.\n" }, { "path": "skills/.curated/chatgpt-apps/references/apps-sdk-docs-workflow.md", "content": "# Apps SDK Docs Workflow\n\nUse this reference to keep code generation aligned with current OpenAI Apps SDK docs.\n\n## Always Fetch These Pages (Baseline)\n\n- `https://developers.openai.com/apps-sdk/build/mcp-server/`\n- `https://developers.openai.com/apps-sdk/build/chatgpt-ui/`\n- `https://developers.openai.com/apps-sdk/build/examples/`\n- `https://developers.openai.com/apps-sdk/plan/tools/`\n- `https://developers.openai.com/apps-sdk/reference/`\n\n## Fetch Conditionally (Greenfield / First Pass)\n\n- `https://developers.openai.com/apps-sdk/quickstart/` for first implementation scaffolds and happy-path wiring\n- `https://developers.openai.com/apps-sdk/deploy/` when the task includes local ChatGPT testing via tunnel, hosting, or production deployment planning\n- `https://developers.openai.com/apps-sdk/deploy/submission/` when the task includes public launch, app review, or publishing steps\n- `https://developers.openai.com/apps-sdk/app-submission-guidelines/` when the task includes submission readiness, policy/reliability checks, or review-risk reduction\n\n## Suggested `openai-docs` / MCP Queries\n\nUse focused searches before fetching:\n\n- `ChatGPT Apps SDK build MCP server register resource template resourceUri outputTemplate`\n- `ChatGPT Apps SDK build ChatGPT UI MCP Apps bridge ui/notifications/tool-result`\n- `ChatGPT Apps SDK examples React widget upload modal Pizzaz`\n- `Apps SDK define tools annotations readOnlyHint destructiveHint openWorldHint`\n- `Apps SDK reference tool descriptor _meta ui.resourceUri openai/outputTemplate`\n- `ChatGPT Apps SDK quickstart build web component tools/call`\n- `ChatGPT app company knowledge compatibility search fetch tools`\n- `platform MCP search tool fetch tool schema`\n- `ChatGPT Apps SDK deploy app local development tunnel ngrok refresh connector`\n- `ChatGPT Apps SDK submit app review prerequisites app submission guidelines`\n\n## Docs-Derived Checklist (Current Guidance)\n\n### Archetype / Shape\n\n- Classify the request into one primary app archetype before choosing examples or scaffolds\n- Keep the repo shape consistent with that archetype instead of inventing a new structure for each prompt\n\n### Server\n\n- Register the widget resource/template with the MCP Apps UI MIME type (`text/html;profile=mcp-app`) or `RESOURCE_MIME_TYPE` when using `@modelcontextprotocol/ext-apps/server`\n- Version template URIs when widget HTML or JS or CSS changes in a breaking way (treat URI as cache key)\n- Set `_meta.ui.resourceUri` on render tools; optionally mirror `_meta[\"openai/outputTemplate\"]` for ChatGPT compatibility\n- Design tool handlers to be idempotent because the model may retry calls\n- Keep `structuredContent` concise and move widget-only payloads to `_meta`\n\n### Tool Design\n\n- Plan one user intent per tool\n- Use action-oriented names and precise descriptions\n- Set tool impact hints accurately (`readOnlyHint`, `destructiveHint`, `openWorldHint`)\n- Split data and render tools so that the model can fetch the data and look at it before choosing to render the widget UI or not\n- Make the widget input a list of unique identifiers (e.g. `propertyIds` for a render property map widget that takes IDs returned from the fetch properties nearby tool) if you want to make sure the widget only renders 1p data; make the widget input semantically relevant if you want to allow the model to render the widget with generated data (e.g. `questionAndAnswerPairs` for a flashcards widget)\n- For connector-like, data-only, sync-oriented, or company-knowledge-style apps, prefer the standard `search` and `fetch` tools by default\n\n### UI\n\n- Prefer the MCP Apps bridge (`ui/*` notifications + `tools/call`) for new apps\n- Prefer `ui/message` for follow-up messaging in baseline examples; treat `window.openai.sendFollowUpMessage` as optional ChatGPT-specific compatibility\n- Treat `window.openai` as compatibility plus optional ChatGPT extensions\n- Render from `structuredContent` and treat host-delivered data as untrusted input\n- Use `ui/update-model-context` only for UI state the model should reason about\n\n### Starting Point Selection\n\n- Check `apps-sdk/build/examples` and the official examples repo before generating a greenfield scaffold from scratch\n- Prefer the smallest upstream example that matches the requested stack and interaction pattern\n- Use the local fallback scaffold only when upstream examples are a poor fit or undesirable for the request\n\n### Resource Metadata / Security\n\n- Set `_meta.ui.csp.connectDomains` and `_meta.ui.csp.resourceDomains` exactly\n- Avoid `frameDomains` unless iframe embedding is central to the experience\n- Set `_meta.ui.domain` for submission-ready apps\n- Always set `openai/widgetDescription` to inform the model what the widget is to be used for\n\n### Developer Mode / Local Testing\n\n- Run the MCP server locally on `http://localhost:/mcp`\n- Expose it with a public HTTPS tunnel for ChatGPT access during development\n- Use the public URL + `/mcp` when adding the app in ChatGPT settings\n- Include ChatGPT Developer Mode setup and app creation steps in implementation handoff\n- Remind users to refresh the app after MCP tool/metadata changes\n- Note terminology differences when relevant: some docs/screenshots may still say \"connector\" while product UI uses \"app\"\n\n### Validation\n\n- Validate against a minimum working repo contract, not just file creation\n- Run the cheapest useful syntax or compile check first\n- If feasible, confirm the local `/mcp` route responds before calling the result “working”\n- If you cannot run a deeper check, say so explicitly\n- If the app is connector-like or sync-oriented, verify the `search` and `fetch` tool shapes against the standard\n\n### Production Hosting / Deploy\n\n- Prefer a stable public HTTPS endpoint with reliable TLS and low-latency streaming `/mcp`\n- Document platform-specific secrets handling and environment variables\n- Include logging/metrics expectations for debugging production tool calls\n- Re-test the hosted endpoint in ChatGPT Developer Mode before submission\n\n### Submission / Review\n\n- Read `deploy/submission` and `app-submission-guidelines` together (process + policy requirements)\n- Check org verification and Owner-role prerequisites before generating submission steps\n- Ensure the endpoint is public production infrastructure (not localhost/tunnel/testing URLs)\n- Ensure CSP is defined and accurate for submission\n- Prepare submission artifacts (metadata, screenshots, privacy policy/support contacts, test prompts/responses)\n- If auth is required, prepare review-safe demo credentials and validate them outside internal networks\n\n## Generation Pattern\n\n1. Classify the app archetype.\n2. Fetch docs with `$openai-docs`.\n3. Check official examples before inventing a scaffold from scratch.\n4. Summarize relevant constraints and metadata keys.\n5. Propose tool plan and architecture.\n6. Adapt the closest example or use the local fallback scaffold.\n7. Generate or patch the server scaffold.\n8. Generate or patch the widget scaffold.\n9. Validate the repo against the minimum working contract.\n10. Add local run + tunnel + ChatGPT Developer Mode app setup instructions.\n11. Add hosting/deployment guidance when the task implies go-live.\n12. Add submission/readiness steps when the user intends public distribution.\n13. Call out compatibility aliases vs MCP Apps standard fields.\n\n## Starter Scaffold Script\n\n- Use `./scripts/scaffold_node_ext_apps.mjs --app-name ` only when the user wants a greenfield Node + `@modelcontextprotocol/ext-apps` starter and no upstream example is the better fit.\n- If the file is not executable in the current environment, fall back to `node scripts/scaffold_node_ext_apps.mjs --app-name `.\n- The script generates `package.json`, `tsconfig.json`, `public/widget.html`, and `src/server.ts`.\n- It intentionally uses the MCP Apps bridge by default, keeps follow-up messaging on `ui/message`, and limits `window.openai` to optional host signals/extensions.\n- After generation, compare the output against the docs you fetched and adjust package versions, metadata, transport details, or URI/versioning if the docs changed.\n" }, { "path": "skills/.curated/chatgpt-apps/references/interactive-state-sync-patterns.md", "content": "# Interactive State Sync Patterns\n\nUse this reference when building ChatGPT apps with long-lived widget state, repeated interactions, or component-initiated tool calls (for example: games, boards, maps, dashboards, editors, or realtime-ish UIs).\n\nDo not load this file for simple read-only render apps unless state sync behavior is part of the task.\n\n## When This Reference Helps\n\nRead this file when the app needs one or more of these patterns:\n\n- Repeated actions that may return similar data (retry, refresh, reset, reroll)\n- UI controls that trigger tool calls after the initial render\n- Local widget behavior that should also work outside ChatGPT during development\n- Multiple tool calls updating one mounted widget over time\n- Clear separation between model-visible state and widget-only state\n\n## Reusable Patterns\n\n### 1. Snapshot + Event Token\n\nReturn a stable state snapshot in `structuredContent` and add a monotonic event token for repeated actions that may not change other fields.\n\nExamples:\n\n- `stateVersion`\n- `refreshCount`\n- `resetCount`\n- `lastMutationId`\n\nUse this when the widget must detect \"same shape, new event\" updates reliably.\n\n### 2. Intent-Focused Tool Surface\n\nPrefer small, explicit tools that map to user-visible actions or data operations.\n\n- Keep names action-oriented\n- Use enums and bounded schemas where possible\n- Avoid kitchen-sink tools that mix unrelated reads and writes\n\nThis improves model tool selection and reduces malformed calls.\n\n### 3. Idempotent Handlers (or Explicitly Non-Idempotent)\n\nDesign handlers to tolerate retries. If a tool is not idempotent, make the side effect explicit and confirm intent in the flow.\n\n- Reads and pure transforms should usually be idempotent\n- Writes should include clear impact hints and current-turn confirmation where needed\n- Repeated calls with the same input should not corrupt widget state\n\n### 4. `structuredContent` / `_meta` Partitioning\n\nPartition payloads intentionally:\n\n- `structuredContent`: concise model-visible state the widget also uses\n- `content`: short narration/status text\n- `_meta`: large maps, caches, or sensitive widget-only hydration data\n\nKeep `structuredContent` small enough for follow-up reasoning and chaining.\n\n### 5. MCP Apps Bridge First, `window.openai` Second\n\nFor new scaffolds:\n\n- Prefer MCP Apps bridge notifications and `tools/call` (portable across hosts)\n- Use `window.openai` as a compatibility layer plus optional ChatGPT extensions\n\nThis keeps the app portable while still enabling ChatGPT-specific capabilities when helpful.\n\n### 6. Component-Initiated Tool Calls Without Remounting\n\nFor interactive widgets, allow the UI to call data/action tools directly and update the existing widget state instead of forcing a full re-render/remount every time.\n\nThis is especially useful for:\n\n- Refresh\n- Retry\n- Rerun\n- Toggle/filter actions\n- Incremental interactions inside one widget session\n\n### 7. Standalone / No-Host Fallback Mode\n\nWhen feasible, make the widget usable without ChatGPT during development:\n\n- If host APIs are unavailable, apply local state directly\n- Preserve basic interactions in a normal browser\n\nThis speeds up front-end iteration and reduces dependence on connector setup for every UI tweak.\n\n### 8. Decouple Data Tools from Render Tools (When Complexity Grows)\n\nUse separate data and render tools when the app has multi-step reasoning or frequent updates.\n\n- Data tools fetch/compute/mutate and return reusable `structuredContent`\n- Render tools attach the widget template and focus on presentation\n\nThis reduces unnecessary remounts and gives the model a chance to refine data before rendering.\n\n## Common Anti-Patterns\n\n- Putting large widget-only blobs into `structuredContent`\n- Attaching a widget template to every tool when only one render tool needs it\n- Using hidden client-side state as the source of truth for critical actions\n- Depending only on `window.openai` APIs for baseline app behavior\n- Using ambiguous tool names that do not match user intent\n\n## Example App Types That Benefit From These Patterns\n\n- Multiplayer or turn-based games\n- Collaborative boards / task views\n- Maps with filters and repeated searches\n- Dashboards with refresh and drill-down actions\n- Editors or builders with iterative tool calls\n" }, { "path": "skills/.curated/chatgpt-apps/references/repo-contract-and-validation.md", "content": "# Repo Contract And Validation\n\nLoad this reference when scaffolding or reviewing a generated ChatGPT app repo.\n\nThe goal is not “files were created.” The goal is “the repo is plausibly runnable and follows a stable working-app contract.”\n\n## Minimum Working Repo Contract\n\nEvery generated repo should satisfy the relevant parts of this contract.\n\n### 1. Shape\n\n- The repo shape matches the chosen archetype.\n- The repo structure is simple enough that a user can identify where the server and widget live.\n\n### 2. Server\n\n- There is a clear MCP server entry point.\n- The server exposes `/mcp`.\n- The server registers tools intentionally.\n- If a UI exists, the server registers a resource/template with the MCP Apps UI MIME type.\n\n### 3. Tools\n\n- Each tool maps to one user intent.\n- Descriptions help the model choose the tool.\n- Required annotations are present and accurate.\n- UI-linked tools use `_meta.ui.resourceUri`.\n- `_meta[\"openai/outputTemplate\"]` is treated as optional compatibility, not the primary contract.\n- When the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, it implements standard `search` and `fetch` tools instead of custom substitutes.\n\n### 4. Widget\n\n- The widget initializes the MCP Apps bridge when needed.\n- The widget can receive `ui/notifications/tool-result`.\n- The widget renders from `structuredContent`.\n- Interactive widgets use `tools/call`.\n- Baseline follow-up messaging uses `ui/message`.\n- `window.openai` is optional and additive.\n\n### 5. Local Developer Experience\n\n- There is a clear way to start the app locally.\n- There is at least one low-cost check command when the stack supports it.\n- The response explains how to connect the app in ChatGPT Developer Mode when relevant.\n\n## Validation Ladder\n\nRun the highest level you can without overfitting to a single stack.\n\n### Level 0: Static contract review\n\nCheck for:\n\n- chosen archetype is sensible\n- repo shape matches archetype\n- `/mcp` route is present\n- tool/resource/widget responsibilities are coherent\n- if the app is connector-like or sync-oriented, `search` and `fetch` are present with the expected standard shape\n\n### Level 1: Syntax or compile checks\n\nUse the stack-appropriate cheapest check available, for example:\n\n- Python syntax check\n- TypeScript compile check\n- framework-specific lint or build sanity check if already installed\n\n### Level 2: Local runtime sanity\n\nIf feasible:\n\n- start the server\n- confirm the health route or `/mcp` endpoint responds\n\n### Level 3: Host loop validation\n\nIf feasible:\n\n- inspect with MCP Inspector\n- test through ChatGPT Developer Mode\n- confirm widget updates after tool results\n\n## Reporting Rule\n\nAlways say which validation level was reached and what was not run.\n\nThat makes the skill more reliable because it separates:\n\n- “repo shape looks right”\n- “syntax is valid”\n- “server starts”\n- “host integration was actually exercised”\n" }, { "path": "skills/.curated/chatgpt-apps/references/search-fetch-standard.md", "content": "# Search And Fetch Standard\n\nLoad this reference when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research.\n\n## Default Rule\n\nIf the app is primarily a read-only knowledge source, do not invent custom equivalents to `search` and `fetch`.\n\nDefault to implementing the standard `search` and `fetch` tools exactly, then add other tools only if the use case clearly needs them.\n\n## When This Applies\n\nUse the standard by default when the request is about:\n\n- a data-only app\n- a sync app\n- a company knowledge source\n- deep research compatibility\n- a connector-like integration over documents, tickets, wiki pages, CRM records, or similar read-only data\n\n## Tool Requirements\n\n### `search`\n\n- Read-only tool\n- Takes a single query string\n- Returns exactly one MCP content item with `type: \"text\"`\n- That text is a JSON-encoded object with:\n - `results`\n - each result has `id`, `title`, and `url`\n\n### `fetch`\n\n- Read-only tool\n- Takes a single document/item id string\n- Returns exactly one MCP content item with `type: \"text\"`\n- That text is a JSON-encoded object with:\n - `id`\n - `title`\n - `text`\n - `url`\n - optional `metadata`\n\n## Implementation Rules\n\n- Match the schema exactly when the app is intended for company knowledge or deep research compatibility.\n- Use canonical `url` values for citations.\n- Mark these tools as read-only.\n- Prefer these names exactly: `search` and `fetch`.\n- If you add other read-only tools, they should complement the standard rather than replace it.\n\n## Validation Checks\n\nWhen `search` and `fetch` are relevant, verify:\n\n- both tools exist\n- they are read-only\n- their input shapes match the standard\n- their returned payloads are wrapped as one `content` item with JSON-encoded `text`\n- result URLs are canonical enough for citation use\n\n## Source\n\nThis standard is described in:\n\n- `https://developers.openai.com/apps-sdk/build/mcp-server/#company-knowledge-compatibility`\n- `https://platform.openai.com/docs/mcp`\n" }, { "path": "skills/.curated/chatgpt-apps/references/upstream-example-workflow.md", "content": "# Upstream Example Workflow\n\nLoad this reference when starting a greenfield ChatGPT app or when deciding whether to adapt an upstream example or use the local fallback scaffold.\n\n## Default Order\n\nPrefer these starting points in order:\n\n1. Official OpenAI Apps SDK examples\n2. Version-matched `@modelcontextprotocol/ext-apps` examples\n3. Local `scripts/scaffold_node_ext_apps.mjs` fallback\n\nThis keeps the skill aligned with current docs and maintained example code while still preserving a low-dependency fallback when examples are not a good fit.\n\n## Choose The Right Source\n\n### 1. Official OpenAI examples\n\nPrefer these when:\n\n- The app is clearly ChatGPT-facing\n- The user wants a polished UI or React component\n- The task involves file upload, modal flows, display-mode changes, or other ChatGPT extensions\n- The docs/examples page already shows a similar interaction pattern\n\nTypical sources:\n\n- `https://developers.openai.com/apps-sdk/build/examples/`\n- `https://github.com/openai/openai-apps-sdk-examples`\n- `https://developers.openai.com/apps-sdk/quickstart/` for the smallest vanilla baseline\n\n### 2. `@modelcontextprotocol/ext-apps` examples\n\nPrefer these when:\n\n- The user needs a lower-level MCP Apps baseline\n- Portability across MCP Apps-compatible hosts matters more than ChatGPT-specific polish\n- You want version-matched examples close to the installed `@modelcontextprotocol/ext-apps` package shape\n\nThis follows the same basic idea as the upstream `create-mcp-app` skill: use maintained examples as the starting point, then adapt them.\n\nTypical examples from upstream flows:\n\n- `examples/demo-vanilla-html`\n- `examples/demo-react-simple`\n- `examples/demo-connectors-api`\n\n### 3. Local fallback scaffold\n\nUse `scripts/scaffold_node_ext_apps.mjs` when:\n\n- No close upstream example exists\n- The user wants a tiny Node + vanilla HTML starter\n- Network/example retrieval is undesirable\n- You need a throwaway starter to patch quickly during a live coding task\n\nDo not prefer the local scaffold just because it is available. It is the fallback, not the default.\n\n## Adaptation Rules\n\n- Copy the smallest matching example, not the entire showcase app.\n- Remove unrelated demo tools, assets, and routes immediately.\n- Keep the upstream file structure when it is already clean and docs-aligned.\n- Reconcile the copied example with the current docs before finishing:\n - tool names and descriptions\n - annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint` when true)\n - `_meta.ui.resourceUri` and optional `_meta[\"openai/outputTemplate\"]`\n - resource `_meta.ui.csp`, `_meta.ui.domain`, and `openai/widgetDescription`\n - URI versioning for template changes\n - local run/test instructions\n- State which example you chose and why.\n- If you rely on upstream code, note the source repo and branch/tag/commit when practical; avoid silently depending on a floating example shape for long-lived work.\n\n## Minimal Selection Heuristic\n\n- If the user asks for **React + polished UI**, start with official OpenAI examples.\n- If the user asks for **vanilla HTML + tiny demo**, start with the quickstart example; use the local fallback scaffold only if the quickstart is still too opinionated or unavailable.\n- If the user asks for **portable MCP Apps wiring**, start with `@modelcontextprotocol/ext-apps` examples.\n- If the user already has an app, adapt their code directly instead of importing a new example.\n" }, { "path": "skills/.curated/chatgpt-apps/references/window-openai-patterns.md", "content": "# Window.openai Patterns\n\nLoad this reference when a task needs ChatGPT-only widget features, when translating older examples that use an `app` wrapper, or when a React widget should read host globals safely.\n\n## Core Rule\n\n- Build baseline widget behavior on the MCP Apps bridge: `ui/*` notifications, `tools/call`, `ui/message`, and `ui/update-model-context`.\n- Use `window.openai` only when the task specifically benefits from ChatGPT-only runtime conveniences.\n- Treat `window.openai` as additive. The app should still have a coherent baseline path on the MCP Apps standard when possible.\n\n## Canonical `window.openai` Surface\n\n### State And Data\n\n- `window.openai.toolInput`: tool arguments supplied by the host\n- `window.openai.toolOutput`: current `structuredContent`\n- `window.openai.toolResponseMetadata`: current `_meta` payload (widget-only)\n- `window.openai.widgetState`: persisted widget-local snapshot\n- `window.openai.setWidgetState(state)`: persist widget-local snapshot after meaningful UI changes\n\n### Runtime APIs\n\n- `window.openai.callTool(name, args)`: call another MCP tool from the widget\n- `window.openai.sendFollowUpMessage({ prompt, scrollToBottom? })`: ask ChatGPT to post a widget-authored follow-up message\n- `window.openai.openExternal({ href, redirectUrl? })`: open an external URL through ChatGPT's vetted flow\n- `window.openai.requestDisplayMode({ mode })`: request `inline`, `pip`, or `fullscreen`\n- `window.openai.requestModal({ params, template? })`: open a host-owned modal\n- `window.openai.requestClose()`: ask ChatGPT to close the widget\n- `window.openai.uploadFile(file)`: upload a file from the widget\n- `window.openai.getFileDownloadUrl({ fileId })`: resolve a temporary download URL\n- `window.openai.notifyIntrinsicHeight(...)`: report dynamic height changes\n- `window.openai.setOpenInAppUrl({ href })`: override the fullscreen punch-out target\n\n### Context Signals\n\n- `window.openai.theme`\n- `window.openai.displayMode`\n- `window.openai.maxHeight`\n- `window.openai.safeArea`\n- `window.openai.view`\n- `window.openai.userAgent`\n- `window.openai.locale`\n\n## Mapping From Repo Wrapper Examples\n\n- `app.callServerTool({ name, arguments })`:\n Use `window.openai.callTool(name, args)` when you intentionally want the ChatGPT compatibility layer.\n Use `tools/call` over the bridge when you want the portable MCP Apps path.\n- `app.sendMessage(...)`:\n Use `ui/message` for portable bridge messaging.\n If the task is intentionally ChatGPT-specific, `window.openai.sendFollowUpMessage({ prompt })` is the closest supported path.\n- `app.updateModelContext(...)`:\n Use `ui/update-model-context` over the bridge.\n This is part of the standard bridge, not a `window.openai` feature.\n- `app.openLink({ url })`:\n Use `window.openai.openExternal({ href: url })` when you intentionally want ChatGPT's external navigation flow.\n- `app.requestDisplayMode({ mode })`:\n Use `window.openai.requestDisplayMode({ mode })`.\n- `app.getHostContext()`:\n Read the documented globals directly (`theme`, `displayMode`, `locale`, `maxHeight`, `safeArea`, `userAgent`).\n- `app.getHostCapabilities()` / `app.getHostVersion()`:\n These are wrapper-level convenience APIs.\n Prefer feature detection (`if (window.openai?.requestModal)`) and the documented globals instead of teaching these as the primary public surface.\n\n## React Helper Extraction\n\n- The repo's `src/use-openai-global.ts` is a good baseline for subscribing to host global changes without scattering direct `window.openai` reads through components.\n- The repo's `src/use-widget-state.ts` is a good baseline for mirroring React state into `window.openai.setWidgetState(...)`.\n- The repo's `src/use-widget-props.ts` is a good baseline for reading typed `toolOutput` with a local fallback.\n- Keep these helpers optional. Do not force a React abstraction when a simple vanilla widget is enough.\n" }, { "path": "skills/.curated/chatgpt-apps/scripts/scaffold_node_ext_apps.mjs", "content": "#!/usr/bin/env node\n\nimport { mkdirSync, writeFileSync, existsSync, readdirSync, lstatSync } from \"node:fs\";\nimport path from \"node:path\";\n\nfunction toSlug(value) {\n const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n return normalized || \"example-chatgpt-app\";\n}\n\nfunction toToolName(value) {\n const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, \"_\").replace(/_+/g, \"_\").replace(/^_+|_+$/g, \"\");\n return normalized || \"show_example\";\n}\n\nfunction toTitle(value) {\n const parts = value.split(/[-_]+/).filter(Boolean);\n return parts.map((part) => part[0].toUpperCase() + part.slice(1)).join(\" \") || \"Example\";\n}\n\nfunction fillTemplate(template, mapping) {\n let result = template;\n for (const [key, value] of Object.entries(mapping)) {\n result = result.replaceAll(key, value);\n }\n return result;\n}\n\nfunction writeFile(filePath, content) {\n mkdirSync(path.dirname(filePath), { recursive: true });\n writeFileSync(filePath, content, \"utf8\");\n}\n\nfunction ensureTargetDir(targetPath, force) {\n if (existsSync(targetPath)) {\n if (!lstatSync(targetPath).isDirectory()) {\n throw new Error(`Output path exists and is not a directory: ${targetPath}`);\n }\n if (readdirSync(targetPath).length > 0 && !force) {\n throw new Error(\n `Refusing to write into non-empty directory: ${targetPath}\\nRe-run with --force to overwrite generated files.`\n );\n }\n }\n\n mkdirSync(targetPath, { recursive: true });\n}\n\nfunction buildPackageJson(appSlug) {\n const packageJson = {\n name: appSlug,\n private: true,\n type: \"module\",\n scripts: {\n dev: \"tsx watch src/server.ts\",\n start: \"tsx src/server.ts\",\n check: \"tsc --noEmit\",\n },\n dependencies: {\n \"@modelcontextprotocol/ext-apps\": \"^1.0.1\",\n \"@modelcontextprotocol/sdk\": \"^1.20.2\",\n zod: \"^3.25.76\",\n },\n devDependencies: {\n \"@types/node\": \"^24.3.0\",\n tsx: \"^4.19.4\",\n typescript: \"^5.9.2\",\n },\n };\n\n return `${JSON.stringify(packageJson, null, 2)}\\n`;\n}\n\nfunction buildTsconfig() {\n return `{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"types\": [\"node\"],\n \"outDir\": \"dist\"\n },\n \"include\": [\"src/**/*.ts\"]\n}\n`;\n}\n\nconst WIDGET_TEMPLATE = `\n\n \n \n \n __APP_TITLE__\n \n \n \n
\n

__APP_TITLE__ starter

\n

Waiting for tool output

\n

Call the __TOOL_NAME__ tool to hydrate this widget.

\n \n \n
\n This widget uses the MCP Apps bridge by default.\n
\n
\n\n \n \n\n`;\n\nconst SERVER_TEMPLATE = `import { createServer } from \"node:http\";\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport {\n registerAppResource,\n registerAppTool,\n RESOURCE_MIME_TYPE,\n} from \"@modelcontextprotocol/ext-apps/server\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { z } from \"zod\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\nconst ROOT_DIR = path.resolve(__dirname, \"..\");\nconst WIDGET_URI = \"__WIDGET_URI__\";\nconst WIDGET_HTML = readFileSync(\n path.join(ROOT_DIR, \"public\", \"widget.html\"),\n \"utf8\"\n);\n\nfunction createAppServer(): McpServer {\n const server = new McpServer({\n name: \"__APP_SLUG__\",\n version: \"0.1.0\",\n });\n\n registerAppResource(\n server,\n \"main-widget\",\n WIDGET_URI,\n {},\n async () => ({\n contents: [\n {\n uri: WIDGET_URI,\n mimeType: RESOURCE_MIME_TYPE,\n text: WIDGET_HTML,\n _meta: {\n ui: {\n prefersBorder: true,\n csp: {\n connectDomains: [],\n resourceDomains: [],\n },\n },\n \"openai/widgetDescription\":\n \"__APP_TITLE__ starter widget rendered by the MCP server.\",\n },\n },\n ],\n })\n );\n\n registerAppTool(\n server,\n \"__TOOL_NAME__\",\n {\n title: \"__APP_TITLE__\",\n description:\n \"Use this when the user wants to render the __APP_TITLE__ starter widget or inspect a minimal Apps SDK tool result.\",\n inputSchema: {\n message: z\n .string()\n .optional()\n .describe(\"Optional message to show inside the widget.\"),\n },\n annotations: {\n readOnlyHint: true,\n destructiveHint: false,\n openWorldHint: false,\n idempotentHint: true,\n },\n _meta: {\n ui: { resourceUri: WIDGET_URI },\n \"openai/toolInvocation/invoking\": \"Loading __APP_TITLE__\",\n \"openai/toolInvocation/invoked\": \"__APP_TITLE__ ready\",\n },\n },\n async ({ message }) => {\n const resolvedMessage =\n message?.trim() ||\n \"This starter uses the MCP Apps bridge first, keeps follow-up messaging on ui/message, and limits window.openai to optional host signals.\";\n\n return {\n content: [\n {\n type: \"text\" as const,\n text: \"Rendered the __APP_TITLE__ starter widget.\",\n },\n ],\n structuredContent: {\n headline: \"__APP_TITLE__\",\n message: resolvedMessage,\n source: \"__TOOL_NAME__\",\n themeHint:\n \"Read window.openai.theme in the widget if you need ChatGPT theme information.\",\n },\n _meta: {\n \"openai/outputTemplate\": WIDGET_URI,\n },\n };\n }\n );\n\n return server;\n}\n\nconst port = Number(process.env.PORT ?? \"__PORT__\");\nconst MCP_PATH = \"/mcp\";\n\ncreateServer(async (req, res) => {\n if (!req.url) {\n res.writeHead(400).end(\"Missing URL\");\n return;\n }\n\n const url = new URL(req.url, \"http://\" + (req.headers.host ?? \"localhost\"));\n const isMcpRoute = url.pathname === MCP_PATH || url.pathname.startsWith(MCP_PATH + \"/\");\n\n if (req.method === \"OPTIONS\" && isMcpRoute) {\n res.writeHead(204, {\n \"Access-Control-Allow-Origin\": \"*\",\n \"Access-Control-Allow-Methods\": \"POST, GET, DELETE, OPTIONS\",\n \"Access-Control-Allow-Headers\": \"content-type, mcp-session-id\",\n \"Access-Control-Expose-Headers\": \"Mcp-Session-Id\",\n });\n res.end();\n return;\n }\n\n if (req.method === \"GET\" && url.pathname === \"/\") {\n res.writeHead(200, { \"content-type\": \"text/plain\" }).end(\"__APP_TITLE__ MCP server\");\n return;\n }\n\n const transportMethods = new Set([\"GET\", \"POST\", \"DELETE\"]);\n if (isMcpRoute && req.method && transportMethods.has(req.method)) {\n res.setHeader(\"Access-Control-Allow-Origin\", \"*\");\n res.setHeader(\"Access-Control-Expose-Headers\", \"Mcp-Session-Id\");\n\n const server = createAppServer();\n const transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: undefined,\n enableJsonResponse: true,\n });\n\n res.on(\"close\", () => {\n transport.close();\n server.close();\n });\n\n try {\n await server.connect(transport);\n await transport.handleRequest(req, res);\n } catch (error) {\n console.error(\"Failed to handle MCP request:\", error);\n if (!res.headersSent) {\n res.writeHead(500).end(\"Internal server error\");\n }\n }\n return;\n }\n\n res.writeHead(404).end(\"Not Found\");\n}).listen(port, () => {\n console.log(\"__APP_TITLE__ MCP server listening on http://localhost:\" + port + MCP_PATH);\n});\n`;\n\nfunction buildWidgetHtml(appSlug, appTitle, toolName) {\n return fillTemplate(WIDGET_TEMPLATE, {\n \"__APP_SLUG__\": appSlug,\n \"__APP_TITLE__\": appTitle,\n \"__TOOL_NAME__\": toolName,\n });\n}\n\nfunction buildServerTs(appSlug, appTitle, toolName, widgetUri, port) {\n return fillTemplate(SERVER_TEMPLATE, {\n \"__APP_SLUG__\": appSlug,\n \"__APP_TITLE__\": appTitle,\n \"__TOOL_NAME__\": toolName,\n \"__WIDGET_URI__\": widgetUri,\n \"__PORT__\": String(port),\n });\n}\n\nfunction usage() {\n return [\n \"Generate a minimal Node + @modelcontextprotocol/ext-apps starter with a vanilla widget that uses the MCP Apps bridge by default.\",\n \"Prefer upstream examples first; use this scaffold as the fallback.\",\n \"\",\n \"Usage:\",\n \" ./scripts/scaffold_node_ext_apps.mjs [--app-name ] [--tool-name ] [--port ] [--force]\",\n \"\",\n \"If the executable bit is unavailable, run:\",\n \" node scripts/scaffold_node_ext_apps.mjs [--app-name ] [--tool-name ] [--port ] [--force]\",\n ].join(\"\\\\n\");\n}\n\nfunction parseArgs(argv) {\n const args = {\n outputDir: null,\n appName: \"example-chatgpt-app\",\n toolName: null,\n port: 8787,\n force: false,\n };\n\n const tokens = [...argv];\n while (tokens.length > 0) {\n const token = tokens.shift();\n\n if (!args.outputDir && !token.startsWith(\"--\")) {\n args.outputDir = token;\n continue;\n }\n\n if (token === \"--app-name\") {\n args.appName = tokens.shift() ?? \"\";\n continue;\n }\n\n if (token === \"--tool-name\") {\n args.toolName = tokens.shift() ?? \"\";\n continue;\n }\n\n if (token === \"--port\") {\n const value = Number(tokens.shift());\n if (!Number.isInteger(value) || value <= 0) {\n throw new Error(\"Expected a positive integer after --port\");\n }\n args.port = value;\n continue;\n }\n\n if (token === \"--force\") {\n args.force = true;\n continue;\n }\n\n if (token === \"--help\" || token === \"-h\") {\n console.log(usage());\n process.exit(0);\n }\n\n throw new Error(`Unknown argument: ${token}`);\n }\n\n if (!args.outputDir) {\n throw new Error(`Missing required output directory.\\\\n\\\\n${usage()}`);\n }\n\n return args;\n}\n\nfunction main() {\n const args = parseArgs(process.argv.slice(2));\n\n const appSlug = toSlug(args.appName);\n const toolName = toToolName(args.toolName || appSlug);\n const appTitle = toTitle(appSlug);\n const widgetUri = \"ui://widget/main-v1.html\";\n\n const outputDir = path.resolve(args.outputDir);\n ensureTargetDir(outputDir, args.force);\n\n const files = new Map([\n [path.join(outputDir, \"package.json\"), buildPackageJson(appSlug)],\n [path.join(outputDir, \"tsconfig.json\"), buildTsconfig()],\n [path.join(outputDir, \"public\", \"widget.html\"), buildWidgetHtml(appSlug, appTitle, toolName)],\n [path.join(outputDir, \"src\", \"server.ts\"), buildServerTs(appSlug, appTitle, toolName, widgetUri, args.port)],\n ]);\n\n for (const [filePath, content] of files) {\n writeFile(filePath, content);\n }\n\n console.log(\"Generated starter scaffold:\");\n for (const filePath of files.keys()) {\n console.log(\" -\", path.relative(outputDir, filePath));\n }\n}\n\ntry {\n main();\n} catch (error) {\n console.error(error instanceof Error ? error.message : String(error));\n process.exit(1);\n}\n" }, { "path": "skills/.curated/cloudflare-deploy/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don\\'t include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/cloudflare-deploy/SKILL.md", "content": "---\nname: cloudflare-deploy\ndescription: Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.\n---\n\n# Cloudflare Deploy\n\nConsolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.\n\n## Prerequisites\n\n- When sandboxing blocks the deployment network calls, rerun with `sandbox_permissions=require_escalated`.\n- The deployment might take a few minutes. Use appropriate timeout values.\n\n## Authentication (Required Before Deploy)\n\nVerify auth before `wrangler deploy`, `wrangler pages deploy`, or `npm run deploy`:\n\n```bash\nnpx wrangler whoami # Shows account if authenticated\n```\n\nNot authenticated? → `references/wrangler/auth.md`\n- Interactive/local: `wrangler login` (one-time OAuth)\n- CI/CD: Set `CLOUDFLARE_API_TOKEN` env var\n\n## Quick Decision Trees\n\n### \"I need to run code\"\n\n```\nNeed to run code?\n├─ Serverless functions at the edge → workers/\n├─ Full-stack web app with Git deploys → pages/\n├─ Stateful coordination/real-time → durable-objects/\n├─ Long-running multi-step jobs → workflows/\n├─ Run containers → containers/\n├─ Multi-tenant (customers deploy code) → workers-for-platforms/\n├─ Scheduled tasks (cron) → cron-triggers/\n├─ Lightweight edge logic (modify HTTP) → snippets/\n├─ Process Worker execution events (logs/observability) → tail-workers/\n└─ Optimize latency to backend infrastructure → smart-placement/\n```\n\n### \"I need to store data\"\n\n```\nNeed storage?\n├─ Key-value (config, sessions, cache) → kv/\n├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)\n├─ Object/file storage (S3-compatible) → r2/\n├─ Message queue (async processing) → queues/\n├─ Vector embeddings (AI/semantic search) → vectorize/\n├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)\n├─ Secrets management → secrets-store/\n├─ Streaming ETL to R2 → pipelines/\n└─ Persistent cache (long-term retention) → cache-reserve/\n```\n\n### \"I need AI/ML\"\n\n```\nNeed AI?\n├─ Run inference (LLMs, embeddings, images) → workers-ai/\n├─ Vector database for RAG/search → vectorize/\n├─ Build stateful AI agents → agents-sdk/\n├─ Gateway for any AI provider (caching, routing) → ai-gateway/\n└─ AI-powered search widget → ai-search/\n```\n\n### \"I need networking/connectivity\"\n\n```\nNeed networking?\n├─ Expose local service to internet → tunnel/\n├─ TCP/UDP proxy (non-HTTP) → spectrum/\n├─ WebRTC TURN server → turn/\n├─ Private network connectivity → network-interconnect/\n├─ Optimize routing → argo-smart-routing/\n├─ Optimize latency to backend (not user) → smart-placement/\n└─ Real-time video/audio → realtimekit/ or realtime-sfu/\n```\n\n### \"I need security\"\n\n```\nNeed security?\n├─ Web Application Firewall → waf/\n├─ DDoS protection → ddos/\n├─ Bot detection/management → bot-management/\n├─ API protection → api-shield/\n├─ CAPTCHA alternative → turnstile/\n└─ Credential leak detection → waf/ (managed ruleset)\n```\n\n### \"I need media/content\"\n\n```\nNeed media?\n├─ Image optimization/transformation → images/\n├─ Video streaming/encoding → stream/\n├─ Browser automation/screenshots → browser-rendering/\n└─ Third-party script management → zaraz/\n```\n\n### \"I need infrastructure-as-code\"\n\n```\nNeed IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)\n```\n\n## Product Index\n\n### Compute & Runtime\n| Product | Reference |\n|---------|-----------|\n| Workers | `references/workers/` |\n| Pages | `references/pages/` |\n| Pages Functions | `references/pages-functions/` |\n| Durable Objects | `references/durable-objects/` |\n| Workflows | `references/workflows/` |\n| Containers | `references/containers/` |\n| Workers for Platforms | `references/workers-for-platforms/` |\n| Cron Triggers | `references/cron-triggers/` |\n| Tail Workers | `references/tail-workers/` |\n| Snippets | `references/snippets/` |\n| Smart Placement | `references/smart-placement/` |\n\n### Storage & Data\n| Product | Reference |\n|---------|-----------|\n| KV | `references/kv/` |\n| D1 | `references/d1/` |\n| R2 | `references/r2/` |\n| Queues | `references/queues/` |\n| Hyperdrive | `references/hyperdrive/` |\n| DO Storage | `references/do-storage/` |\n| Secrets Store | `references/secrets-store/` |\n| Pipelines | `references/pipelines/` |\n| R2 Data Catalog | `references/r2-data-catalog/` |\n| R2 SQL | `references/r2-sql/` |\n\n### AI & Machine Learning\n| Product | Reference |\n|---------|-----------|\n| Workers AI | `references/workers-ai/` |\n| Vectorize | `references/vectorize/` |\n| Agents SDK | `references/agents-sdk/` |\n| AI Gateway | `references/ai-gateway/` |\n| AI Search | `references/ai-search/` |\n\n### Networking & Connectivity\n| Product | Reference |\n|---------|-----------|\n| Tunnel | `references/tunnel/` |\n| Spectrum | `references/spectrum/` |\n| TURN | `references/turn/` |\n| Network Interconnect | `references/network-interconnect/` |\n| Argo Smart Routing | `references/argo-smart-routing/` |\n| Workers VPC | `references/workers-vpc/` |\n\n### Security\n| Product | Reference |\n|---------|-----------|\n| WAF | `references/waf/` |\n| DDoS Protection | `references/ddos/` |\n| Bot Management | `references/bot-management/` |\n| API Shield | `references/api-shield/` |\n| Turnstile | `references/turnstile/` |\n\n### Media & Content\n| Product | Reference |\n|---------|-----------|\n| Images | `references/images/` |\n| Stream | `references/stream/` |\n| Browser Rendering | `references/browser-rendering/` |\n| Zaraz | `references/zaraz/` |\n\n### Real-Time Communication\n| Product | Reference |\n|---------|-----------|\n| RealtimeKit | `references/realtimekit/` |\n| Realtime SFU | `references/realtime-sfu/` |\n\n### Developer Tools\n| Product | Reference |\n|---------|-----------|\n| Wrangler | `references/wrangler/` |\n| Miniflare | `references/miniflare/` |\n| C3 | `references/c3/` |\n| Observability | `references/observability/` |\n| Analytics Engine | `references/analytics-engine/` |\n| Web Analytics | `references/web-analytics/` |\n| Sandbox | `references/sandbox/` |\n| Workerd | `references/workerd/` |\n| Workers Playground | `references/workers-playground/` |\n\n### Infrastructure as Code\n| Product | Reference |\n|---------|-----------|\n| Pulumi | `references/pulumi/` |\n| Terraform | `references/terraform/` |\n| API | `references/api/` |\n\n### Other Services\n| Product | Reference |\n|---------|-----------|\n| Email Routing | `references/email-routing/` |\n| Email Workers | `references/email-workers/` |\n| Static Assets | `references/static-assets/` |\n| Bindings | `references/bindings/` |\n| Cache Reserve | `references/cache-reserve/` |\n\n## Troubleshooting\n\n### Escalated Network Access\n\nIf deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use `sandbox_permissions=require_escalated`). The deploy requires escalated network access when sandbox networking blocks outbound requests.\n\nExample guidance to the user:\n\n```\nThe deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/agents/openai.yaml", "content": "interface:\n display_name: \"Cloudflare Deploy\"\n short_description: \"Deploy Workers, Pages, and platform services on Cloudflare\"\n icon_small: \"./assets/cloudflare-small.svg\"\n icon_large: \"./assets/cloudflare.png\"\n default_prompt: \"Deploy this app to Cloudflare (Workers or Pages) and return URL, config, and required env vars.\"\n" }, { "path": "skills/.curated/cloudflare-deploy/references/agents-sdk/README.md", "content": "# Cloudflare Agents SDK\n\nCloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.\n\n## Core Value\nBuild stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.\n\n## When to Use\n- Persistent state + memory required\n- Real-time WebSocket connections\n- Long-running workflows (minutes/hours)\n- Chat interfaces with AI models\n- Scheduled/recurring tasks with state\n- DB queries with agent state\n\n## What Type of Agent?\n\n| Use Case | Class | Key Features |\n|----------|-------|--------------|\n| AI chat interface | `AIChatAgent` | Auto-streaming, tools, message history, resumable |\n| MCP tool provider | `Agent` + MCP | Expose tools to AI systems |\n| Custom logic/routing | `Agent` | Full control, WebSockets, email, SQL |\n| Real-time collaboration | `Agent` | WebSocket state, broadcasts |\n| Email processing | `Agent` | `onEmail()` handler |\n\n## Quick Start\n\n**AI Chat Agent:**\n```typescript\nimport { AIChatAgent } from \"agents\";\nimport { openai } from \"@ai-sdk/openai\";\n\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage(onFinish) {\n return this.streamText({\n model: openai(\"gpt-4\"),\n messages: this.messages,\n onFinish,\n });\n }\n}\n```\n\n**Base Agent:**\n```typescript\nimport { Agent } from \"agents\";\n\nexport class MyAgent extends Agent {\n onStart() {\n this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;\n }\n \n async onRequest(request: Request) {\n return Response.json({ state: this.state });\n }\n}\n```\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| Quick start | README only |\n| Build chat agent | README → api.md (AIChatAgent) → patterns.md |\n| Setup project | README → configuration.md |\n| Add React frontend | README → api.md (Client Hooks) → patterns.md |\n| Build MCP server | api.md (MCP) → patterns.md |\n| Background tasks | api.md (Scheduling, Task Queue) → patterns.md |\n| Debug issues | gotchas.md |\n\n## Package Entry Points\n\n| Import | Purpose |\n|--------|---------|\n| `agents` | Server-side Agent classes, lifecycle |\n| `agents/react` | `useAgent()` hook for WebSocket connections |\n| `agents/ai-react` | `useAgentChat()` hook for AI chat UIs |\n\n## In This Reference\n- [configuration.md](./configuration.md) - SDK setup, wrangler config, routing\n- [api.md](./api.md) - Agent classes, lifecycle, client hooks\n- [patterns.md](./patterns.md) - Common workflows, best practices\n- [gotchas.md](./gotchas.md) - Common issues, limits\n\n## See Also\n- durable-objects - Agent infrastructure\n- d1 - External database integration\n- workers-ai - AI model integration\n- vectorize - Vector search for RAG patterns" }, { "path": "skills/.curated/cloudflare-deploy/references/agents-sdk/api.md", "content": "# API Reference\n\n## Agent Classes\n\n### AIChatAgent\n\nFor AI chat with auto-streaming, message history, tools, resumable streaming.\n\n```ts\nimport { AIChatAgent } from \"agents\";\nimport { openai } from \"@ai-sdk/openai\";\n\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage(onFinish) {\n return this.streamText({\n model: openai(\"gpt-4\"),\n messages: this.messages, // Auto-managed message history\n tools: {\n getWeather: {\n description: \"Get weather\",\n parameters: z.object({ city: z.string() }),\n execute: async ({ city }) => `Sunny, 72°F in ${city}`\n }\n },\n onFinish, // Persist response to this.messages\n });\n }\n}\n```\n\n### Agent (Base Class)\n\nFull control for custom logic, WebSockets, email, and SQL.\n\n```ts\nimport { Agent } from \"agents\";\n\nexport class MyAgent extends Agent {\n // Lifecycle methods below\n}\n```\n\n**Type params:** `Agent` - Env bindings, agent state, connection state\n\n## Lifecycle Hooks\n\n```ts\nonStart() { // Init/restart\n this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT, name TEXT)`;\n}\n\nasync onRequest(req: Request) { // HTTP\n const {pathname} = new URL(req.url);\n if (pathname === \"/users\") return Response.json(this.sql<{id,name}>`SELECT * FROM users`);\n return new Response(\"Not found\", {status: 404});\n}\n\nasync onConnect(conn: Connection, ctx: ConnectionContext) { // WebSocket\n conn.accept();\n conn.setState({userId: ctx.request.headers.get(\"X-User-ID\")});\n conn.send(JSON.stringify({type: \"connected\", state: this.state}));\n}\n\nasync onMessage(conn: Connection, msg: WSMessage) { // WS messages\n const m = JSON.parse(msg as string);\n this.setState({messages: [...this.state.messages, m]});\n this.connections.forEach(c => c.send(JSON.stringify(m)));\n}\n\nasync onEmail(email: AgentEmail) { // Email routing\n this.sql`INSERT INTO emails (from_addr,subject,body) VALUES (${email.from},${email.headers.get(\"subject\")},${await email.text()})`;\n}\n```\n\n## State, SQL, Scheduling\n\n```ts\n// State\nthis.setState({count: 42}); // Auto-syncs\nthis.setState({...this.state, count: this.state.count + 1});\n\n// SQL (parameterized queries prevent injection)\nthis.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;\nthis.sql`INSERT INTO users (id,name) VALUES (${userId},${name})`;\nconst users = this.sql<{id,name}>`SELECT * FROM users WHERE id = ${userId}`;\n\n// Scheduling\nawait this.schedule(new Date(\"2026-12-25\"), \"sendGreeting\", {msg:\"Hi\"}); // Date\nawait this.schedule(60, \"checkStatus\", {}); // Delay (sec)\nawait this.schedule(\"0 0 * * *\", \"dailyCleanup\", {}); // Cron\nawait this.cancelSchedule(scheduleId);\n```\n\n## RPC Methods (@callable)\n\n```ts\nimport { Agent, callable } from \"agents\";\n\nexport class MyAgent extends Agent {\n @callable()\n async processTask(input: {text: string}): Promise<{result: string}> {\n return { result: await this.env.AI.run(\"@cf/meta/llama-3.1-8b-instruct\", {prompt: input.text}) };\n }\n}\n// Client: const result = await agent.processTask({ text: \"Hello\" });\n// Must return JSON-serializable values\n```\n\n## Connections & AI\n\n```ts\n// Connections (type: Agent)\nthis.connections.forEach(c => c.send(JSON.stringify(msg))); // Broadcast\nconn.setState({userId:\"123\"}); conn.close(1000, \"Goodbye\");\n\n// Workers AI\nconst r = await this.env.AI.run(\"@cf/meta/llama-3.1-8b-instruct\", {prompt});\n\n// Manual streaming (prefer AIChatAgent)\nconst stream = await client.chat.completions.create({model: \"gpt-4\", messages, stream: true});\nfor await (const chunk of stream) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));\n```\n\n**Type-safe state:** `Agent` - third param types `conn.state`\n\n## MCP Integration\n\nModel Context Protocol for exposing tools:\n\n```ts\n// Register & use MCP server\nawait this.mcp.registerServer(\"github\", {\n url: env.MCP_SERVER_URL,\n auth: { type: \"oauth\", clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET }\n});\nconst tools = await this.mcp.getAITools([\"github\"]);\nreturn this.streamText({ model: openai(\"gpt-4\"), messages: this.messages, tools, onFinish });\n```\n\n## Task Queue\n\n```ts\nawait this.queue(\"processVideo\", { videoId: \"abc123\" }); // Add task\nconst tasks = await this.dequeue(10); // Process up to 10\n```\n\n## Context & Cleanup\n\n```ts\nconst agent = getCurrentAgent(); // Get current instance\nasync destroy() { /* cleanup before agent destroyed */ }\n```\n\n## AI Integration\n\n```ts\n// Workers AI\nconst r = await this.env.AI.run(\"@cf/meta/llama-3.1-8b-instruct\", {prompt});\n\n// Manual streaming (prefer AIChatAgent for auto-streaming)\nconst stream = await client.chat.completions.create({model: \"gpt-4\", messages, stream: true});\nfor await (const chunk of stream) {\n if (chunk.choices[0]?.delta?.content) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));\n}\n```\n\n## Client Hooks (React)\n\n```ts\n// useAgent() - WebSocket connection + RPC\nimport { useAgent } from \"agents/react\";\nconst agent = useAgent({ agent: \"MyAgent\", name: \"user-123\" }); // name for idFromName\nconst result = await agent.processTask({ text: \"Hello\" }); // Call @callable methods\n// agent.readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED\n\n// useAgentChat() - AI chat UI\nimport { useAgentChat } from \"agents/ai-react\";\nconst agent = useAgent({ agent: \"ChatAgent\" });\nconst { messages, input, handleInputChange, handleSubmit, isLoading, stop, clearHistory } = \n useAgentChat({ \n agent, \n maxSteps: 5, // Max tool iterations\n resume: true, // Auto-resume on disconnect\n onToolCall: async (toolCall) => {\n // Client tools (human-in-the-loop)\n if (toolCall.toolName === \"confirm\") return { ok: window.confirm(\"Proceed?\") };\n }\n });\n// status: \"ready\" | \"submitted\" | \"streaming\" | \"error\"\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/agents-sdk/configuration.md", "content": "# Configuration\n\n## Wrangler Setup\n\n```jsonc\n{\n \"name\": \"my-agents-app\",\n \"durable_objects\": {\n \"bindings\": [\n {\"name\": \"MyAgent\", \"class_name\": \"MyAgent\"}\n ]\n },\n \"migrations\": [\n {\"tag\": \"v1\", \"new_sqlite_classes\": [\"MyAgent\"]}\n ],\n \"ai\": {\n \"binding\": \"AI\"\n }\n}\n```\n\n## Environment Bindings\n\n**Type-safe pattern:**\n\n```typescript\ninterface Env {\n AI?: Ai; // Workers AI\n MyAgent?: DurableObjectNamespace;\n ChatAgent?: DurableObjectNamespace;\n DB?: D1Database; // D1 database\n KV?: KVNamespace; // KV storage\n R2?: R2Bucket; // R2 bucket\n OPENAI_API_KEY?: string; // Secrets\n GITHUB_CLIENT_ID?: string; // MCP OAuth credentials\n GITHUB_CLIENT_SECRET?: string;\n QUEUE?: Queue; // Queues\n}\n```\n\n**Best practice:** Define all DO bindings in Env interface for type safety.\n\n## Deployment\n\n```bash\n# Local dev\nnpx wrangler dev\n\n# Deploy production\nnpx wrangler deploy\n\n# Set secrets\nnpx wrangler secret put OPENAI_API_KEY\n```\n\n## Agent Routing\n\n**Recommended: Use route helpers**\n\n```typescript\nimport { routeAgent } from \"agents\";\n\nexport default {\n fetch(request: Request, env: Env) {\n return routeAgent(request, env);\n }\n}\n```\n\nHelper routes requests to agents automatically based on URL patterns.\n\n**Manual routing (advanced):**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env) {\n const url = new URL(request.url);\n \n // Named ID (deterministic)\n const id = env.MyAgent.idFromName(\"user-123\");\n \n // Random ID (from URL param)\n // const id = env.MyAgent.idFromString(url.searchParams.get(\"id\"));\n \n const stub = env.MyAgent.get(id);\n return stub.fetch(request);\n }\n}\n```\n\n**Multi-agent setup:**\n\n```typescript\nimport { routeAgent } from \"agents\";\n\nexport default {\n fetch(request: Request, env: Env) {\n const url = new URL(request.url);\n \n // Route by path\n if (url.pathname.startsWith(\"/chat\")) {\n return routeAgent(request, env, \"ChatAgent\");\n }\n if (url.pathname.startsWith(\"/task\")) {\n return routeAgent(request, env, \"TaskAgent\");\n }\n \n return new Response(\"Not found\", { status: 404 });\n }\n}\n```\n\n## Email Routing\n\n**Code setup:**\n\n```typescript\nimport { routeAgentEmail } from \"agents\";\n\nexport default {\n fetch: (req: Request, env: Env) => routeAgent(req, env),\n email: (message: ForwardableEmailMessage, env: Env) => {\n return routeAgentEmail(message, env);\n }\n}\n```\n\n**Dashboard setup:**\n\nConfigure email routing in Cloudflare dashboard:\n\n```\nDestination: Workers with Durable Objects\nWorker: my-agents-app\n```\n\nThen handle in agent:\n\n```typescript\nexport class EmailAgent extends Agent {\n async onEmail(email: AgentEmail) {\n const text = await email.text();\n // Process email\n }\n}\n```\n\n## AI Gateway (Optional)\n\n```typescript\n// Enable caching/routing through AI Gateway\nconst response = await this.env.AI.run(\n \"@cf/meta/llama-3.1-8b-instruct\",\n { prompt },\n {\n gateway: {\n id: \"my-gateway-id\",\n skipCache: false,\n cacheTtl: 3600\n }\n }\n);\n```\n\n## MCP Configuration (Optional)\n\nFor exposing tools via Model Context Protocol:\n\n```typescript\n// wrangler.jsonc - Add MCP OAuth secrets\n{\n \"vars\": {\n \"MCP_SERVER_URL\": \"https://mcp.example.com\"\n }\n}\n\n// Set secrets via CLI\n// npx wrangler secret put GITHUB_CLIENT_ID\n// npx wrangler secret put GITHUB_CLIENT_SECRET\n```\n\nThen register in agent code (see api.md MCP section).\n" }, { "path": "skills/.curated/cloudflare-deploy/references/agents-sdk/gotchas.md", "content": "# Gotchas & Best Practices\n\n## Common Errors\n\n### \"setState() not syncing\"\n\n**Cause:** Mutating state directly or not calling `setState()` after modifications \n**Solution:** Always use `setState()` with immutable updates:\n```ts\n// ❌ this.state.count++\n// ✅ this.setState({...this.state, count: this.state.count + 1})\n```\n\n### \"Message history grows unbounded (AIChatAgent)\"\n\n**Cause:** `this.messages` in `AIChatAgent` accumulates all messages indefinitely \n**Solution:** Manually trim old messages periodically:\n```ts\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage(onFinish) {\n // Keep only last 50 messages\n if (this.messages.length > 50) {\n this.messages = this.messages.slice(-50);\n }\n \n return this.streamText({ model: openai(\"gpt-4\"), messages: this.messages, onFinish });\n }\n}\n```\n\n### \"SQL injection vulnerability\"\n\n**Cause:** Direct string interpolation in SQL queries\n**Solution:** Use parameterized queries:\n```ts\n// ❌ this.sql`...WHERE id = '${userId}'`\n// ✅ this.sql`...WHERE id = ${userId}`\n```\n\n### \"WebSocket connection timeout\"\n\n**Cause:** Not calling `conn.accept()` in `onConnect`\n**Solution:** Always accept connections:\n```ts\nasync onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: \"123\"}); }\n```\n\n### \"Schedule limit exceeded\"\n\n**Cause:** More than 1000 scheduled tasks per agent\n**Solution:** Clean up old schedules and limit creation rate:\n```ts\nasync checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn(\"Near limit!\"); }\n```\n\n### \"AI Gateway unavailable\"\n\n**Cause:** AI service timeout or quota exceeded \n**Solution:** Add error handling and fallbacks:\n```ts\ntry { \n return await this.env.AI.run(model, {prompt}); \n} catch (e) { \n console.error(\"AI error:\", e);\n return {error: \"Unavailable\"}; \n}\n```\n\n### \"@callable method returns undefined\"\n\n**Cause:** Method doesn't return JSON-serializable value, or has non-serializable types \n**Solution:** Ensure return values are plain objects/arrays/primitives:\n```ts\n// ❌ Returns class instance\n@callable()\nasync getData() { return new Date(); }\n\n// ✅ Returns serializable object\n@callable()\nasync getData() { return { timestamp: Date.now() }; }\n```\n\n### \"Resumable stream not resuming\"\n\n**Cause:** Stream ID must be deterministic for resumption to work \n**Solution:** Use AIChatAgent (automatic) or ensure consistent stream IDs:\n```ts\n// AIChatAgent handles this automatically\nexport class ChatAgent extends AIChatAgent {\n // Resumption works out of the box\n}\n```\n\n### \"MCP connection loss on hibernation\"\n\n**Cause:** MCP server connections don't survive hibernation \n**Solution:** Re-register servers in `onStart()` or check connection status:\n```ts\nonStart() {\n // Re-register MCP servers after hibernation\n await this.mcp.registerServer(\"github\", { url: env.MCP_URL, auth: {...} });\n}\n```\n\n### \"Agent not found\"\n\n**Cause:** Durable Object binding missing or incorrect class name \n**Solution:** Verify DO binding in wrangler.jsonc and class name matches\n\n## Rate Limits & Quotas\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| CPU per request | 30s (std), 300s (max) | Set in wrangler.jsonc |\n| Memory per instance | 128MB | Shared with WebSockets |\n| Storage per agent | 10GB | SQLite storage |\n| Scheduled tasks | 1000 per agent | Monitor with `getSchedules()` |\n| WebSocket connections | Unlimited | Within memory limits |\n| SQL columns | 100 | Per table |\n| SQL row size | 2MB | Key + value |\n| WebSocket message | 32MiB | Max size |\n| DO requests/sec | ~1000 | Per unique DO instance; rate limit if needed |\n| AI Gateway (Workers AI) | Model-specific | Check dashboard for limits |\n| MCP requests | Depends on server | Implement retry/backoff |\n\n## Best Practices\n\n### State Management\n- Use immutable updates: `setState({...this.state, key: newValue})`\n- Trim unbounded arrays (messages, logs) periodically\n- Store large data in SQL, not state\n\n### SQL Usage\n- Create tables in `onStart()`, not `onRequest()`\n- Use parameterized queries: `` sql`WHERE id = ${id}` `` (NOT `` sql`WHERE id = '${id}'` ``)\n- Index frequently queried columns\n\n### Scheduling\n- Monitor schedule count: `await this.getSchedules()`\n- Cancel completed tasks to stay under 1000 limit\n- Use cron strings for recurring tasks\n\n### WebSockets\n- Always call `conn.accept()` in `onConnect()`\n- Handle client disconnects gracefully\n- Broadcast to `this.connections` efficiently\n\n### AI Integration\n- Use `AIChatAgent` for chat interfaces (auto-streaming, resumption)\n- Trim message history to avoid token limits\n- Handle AI errors with try/catch and fallbacks\n\n### Production Deployment\n- **Rate limiting:** Implement request throttling for high-traffic agents (>1000 req/s)\n- **Monitoring:** Log critical errors, track schedule count, monitor storage usage\n- **Graceful degradation:** Handle AI service outages with fallbacks\n- **Message trimming:** Enforce max history length (e.g., 100 messages) in AIChatAgent\n- **MCP reliability:** Re-register servers on hibernation, implement retry logic\n" }, { "path": "skills/.curated/cloudflare-deploy/references/agents-sdk/patterns.md", "content": "# Patterns & Use Cases\n\n## AI Chat w/Tools\n\n**Server (AIChatAgent):**\n\n```ts\nimport { AIChatAgent } from \"agents\";\nimport { openai } from \"@ai-sdk/openai\";\nimport { tool } from \"ai\";\nimport { z } from \"zod\";\n\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage(onFinish) {\n return this.streamText({\n model: openai(\"gpt-4\"),\n messages: this.messages, // Auto-managed\n tools: {\n getWeather: tool({\n description: \"Get current weather\",\n parameters: z.object({ city: z.string() }),\n execute: async ({ city }) => `Weather in ${city}: Sunny, 72°F`\n }),\n searchDocs: tool({\n description: \"Search documentation\",\n parameters: z.object({ query: z.string() }),\n execute: async ({ query }) => JSON.stringify(\n this.sql<{title, content}>`SELECT title, content FROM docs WHERE content LIKE ${'%' + query + '%'}`\n )\n })\n },\n onFinish,\n });\n }\n}\n```\n\n**Client (React):**\n\n```tsx\nimport { useAgent } from \"agents/react\";\nimport { useAgentChat } from \"agents/ai-react\";\n\nfunction ChatUI() {\n const agent = useAgent({ agent: \"ChatAgent\" });\n const { messages, input, handleInputChange, handleSubmit, isLoading } = useAgentChat({ agent });\n \n return (\n
\n {messages.map(m =>
{m.role}: {m.content}
)}\n
\n \n \n
\n
\n );\n}\n```\n\n## Human-in-the-Loop (Client Tools)\n\nServer defines tool, client executes:\n\n```ts\n// Server\nexport class ChatAgent extends AIChatAgent {\n async onChatMessage(onFinish) {\n return this.streamText({\n model: openai(\"gpt-4\"),\n messages: this.messages,\n tools: {\n confirmAction: tool({\n description: \"Ask user to confirm\",\n parameters: z.object({ action: z.string() }),\n execute: \"client\", // Client-side execution\n })\n },\n onFinish,\n });\n }\n}\n\n// Client\nconst { messages } = useAgentChat({\n agent,\n onToolCall: async (toolCall) => {\n if (toolCall.toolName === \"confirmAction\") {\n return { confirmed: window.confirm(`Confirm: ${toolCall.args.action}?`) };\n }\n }\n});\n```\n\n## Task Queue & Scheduled Processing\n\n```ts\nexport class TaskAgent extends Agent {\n onStart() { \n this.schedule(\"*/5 * * * *\", \"processQueue\", {}); // Every 5 min\n this.schedule(\"0 0 * * *\", \"dailyCleanup\", {}); // Daily\n }\n \n async onRequest(req: Request) {\n await this.queue(\"processVideo\", { videoId: (await req.json()).videoId });\n return Response.json({ queued: true });\n }\n \n async processQueue() {\n const tasks = await this.dequeue(10);\n for (const task of tasks) {\n if (task.name === \"processVideo\") await this.processVideo(task.data.videoId);\n }\n }\n \n async dailyCleanup() {\n this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`;\n }\n}\n```\n\n## Manual WebSocket Chat\n\nCustom protocols (non-AI):\n\n```ts\nexport class ChatAgent extends Agent {\n async onConnect(conn: Connection, ctx: ConnectionContext) {\n conn.accept();\n conn.setState({userId: ctx.request.headers.get(\"X-User-ID\") || \"anon\"});\n conn.send(JSON.stringify({type: \"history\", messages: this.state.messages}));\n }\n \n async onMessage(conn: Connection, msg: WSMessage) {\n const newMsg = {userId: conn.state.userId, text: JSON.parse(msg as string).text, timestamp: Date.now()};\n this.setState({messages: [...this.state.messages, newMsg]});\n this.connections.forEach(c => c.send(JSON.stringify(newMsg)));\n }\n}\n```\n\n## Email Processing w/AI\n\n```ts\nexport class EmailAgent extends Agent {\n async onEmail(email: AgentEmail) {\n const [text, from, subject] = [await email.text(), email.from, email.headers.get(\"subject\") || \"\"];\n this.sql`INSERT INTO emails (from_addr, subject, body) VALUES (${from}, ${subject}, ${text})`;\n \n const { text: summary } = await generateText({\n model: openai(\"gpt-4o-mini\"), prompt: `Summarize: ${subject}\\n\\n${text}`\n });\n \n this.connections.forEach(c => c.send(JSON.stringify({type: \"new_email\", from, summary})));\n if (summary.includes(\"urgent\")) await this.schedule(0, \"sendAutoReply\", { to: from });\n }\n}\n```\n\n## Real-time Collaboration\n\n```ts\nexport class GameAgent extends Agent {\n initialState = { players: [], gameStarted: false };\n \n async onConnect(conn: Connection, ctx: ConnectionContext) {\n conn.accept();\n const playerId = ctx.request.headers.get(\"X-Player-ID\") || crypto.randomUUID();\n conn.setState({ playerId });\n \n const newPlayer = { id: playerId, score: 0 };\n this.setState({...this.state, players: [...this.state.players, newPlayer]});\n this.connections.forEach(c => c.send(JSON.stringify({type: \"player_joined\", player: newPlayer})));\n }\n \n async onMessage(conn: Connection, msg: WSMessage) {\n const m = JSON.parse(msg as string);\n \n if (m.type === \"move\") {\n this.setState({\n ...this.state,\n players: this.state.players.map(p => p.id === conn.state.playerId ? {...p, score: p.score + m.points} : p)\n });\n this.connections.forEach(c => c.send(JSON.stringify({type: \"player_moved\", playerId: conn.state.playerId})));\n }\n \n if (m.type === \"start\" && this.state.players.length >= 2) {\n this.setState({...this.state, gameStarted: true});\n this.connections.forEach(c => c.send(JSON.stringify({type: \"game_started\"})));\n }\n }\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/README.md", "content": "# Cloudflare AI Gateway\n\nExpert guidance for implementing Cloudflare AI Gateway - a universal gateway for AI model providers with analytics, caching, rate limiting, and routing capabilities.\n\n## When to Use This Reference\n\n- Setting up AI Gateway for any AI provider (OpenAI, Anthropic, Workers AI, etc.)\n- Implementing caching, rate limiting, or request retry/fallback\n- Configuring dynamic routing with A/B testing or model fallbacks\n- Managing provider API keys securely with BYOK\n- Adding security features (guardrails, DLP)\n- Setting up observability with logging and custom metadata\n- Debugging AI Gateway requests or optimizing configurations\n\n## Quick Start\n\n**What's your setup?**\n\n- **Using Vercel AI SDK** → Pattern 1 (recommended) - see [sdk-integration.md](./sdk-integration.md)\n- **Using OpenAI SDK** → Pattern 2 - see [sdk-integration.md](./sdk-integration.md)\n- **Cloudflare Worker + Workers AI** → Pattern 3 - see [sdk-integration.md](./sdk-integration.md)\n- **Direct HTTP (any language)** → Pattern 4 - see [configuration.md](./configuration.md)\n- **Framework (LangChain, etc.)** → See [sdk-integration.md](./sdk-integration.md)\n\n## Pattern 1: Vercel AI SDK (Recommended)\n\nMost modern pattern using official `ai-gateway-provider` package with automatic fallbacks.\n\n```typescript\nimport { createAiGateway } from 'ai-gateway-provider';\nimport { createOpenAI } from '@ai-sdk/openai';\nimport { generateText } from 'ai';\n\nconst gateway = createAiGateway({\n accountId: process.env.CF_ACCOUNT_ID,\n gateway: process.env.CF_GATEWAY_ID,\n});\n\nconst openai = createOpenAI({ \n apiKey: process.env.OPENAI_API_KEY \n});\n\n// Single model\nconst { text } = await generateText({\n model: gateway(openai('gpt-4o')),\n prompt: 'Hello'\n});\n\n// Automatic fallback array\nconst { text } = await generateText({\n model: gateway([\n openai('gpt-4o'), // Try first\n anthropic('claude-sonnet-4-5'), // Fallback\n ]),\n prompt: 'Hello'\n});\n```\n\n**Install:** `npm install ai-gateway-provider ai @ai-sdk/openai @ai-sdk/anthropic`\n\n## Pattern 2: OpenAI SDK\n\nDrop-in replacement for OpenAI API with multi-provider support.\n\n```typescript\nimport OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat`,\n defaultHeaders: {\n 'cf-aig-authorization': `Bearer ${cfToken}` // For authenticated gateways\n }\n});\n\n// Switch providers by changing model format: {provider}/{model}\nconst response = await client.chat.completions.create({\n model: 'openai/gpt-4o', // or 'anthropic/claude-sonnet-4-5'\n messages: [{ role: 'user', content: 'Hello!' }]\n});\n```\n\n## Pattern 3: Workers AI Binding\n\nFor Cloudflare Workers using Workers AI.\n\n```typescript\nexport default {\n async fetch(request, env, ctx) {\n const response = await env.AI.run(\n '@cf/meta/llama-3-8b-instruct',\n { messages: [{ role: 'user', content: 'Hello!' }] },\n { \n gateway: { \n id: 'my-gateway',\n metadata: { userId: '123', team: 'engineering' }\n } \n }\n );\n \n return Response.json(response);\n }\n};\n```\n\n## Headers Quick Reference\n\n| Header | Purpose | Example | Notes |\n|--------|---------|---------|-------|\n| `cf-aig-authorization` | Gateway auth | `Bearer {token}` | Required for authenticated gateways |\n| `cf-aig-metadata` | Tracking | `{\"userId\":\"x\"}` | Max 5 entries, flat structure |\n| `cf-aig-cache-ttl` | Cache duration | `3600` | Seconds, min 60, max 2592000 (30 days) |\n| `cf-aig-skip-cache` | Bypass cache | `true` | - |\n| `cf-aig-cache-key` | Custom cache key | `my-key` | Must be unique per response |\n| `cf-aig-collect-log` | Skip logging | `false` | Default: true |\n| `cf-aig-cache-status` | Cache hit/miss | Response only | `HIT` or `MISS` |\n\n## In This Reference\n\n| File | Purpose |\n|------|---------|\n| [sdk-integration.md](./sdk-integration.md) | Vercel AI SDK, OpenAI SDK, Workers binding patterns |\n| [configuration.md](./configuration.md) | Dashboard setup, wrangler, API tokens |\n| [features.md](./features.md) | Caching, rate limits, guardrails, DLP, BYOK, unified billing |\n| [dynamic-routing.md](./dynamic-routing.md) | Fallbacks, A/B testing, conditional routing |\n| [troubleshooting.md](./troubleshooting.md) | Debugging, errors, observability, gotchas |\n\n## Reading Order\n\n| Task | Files |\n|------|-------|\n| First-time setup | README + [configuration.md](./configuration.md) |\n| SDK integration | README + [sdk-integration.md](./sdk-integration.md) |\n| Enable caching | README + [features.md](./features.md) |\n| Setup fallbacks | README + [dynamic-routing.md](./dynamic-routing.md) |\n| Debug errors | README + [troubleshooting.md](./troubleshooting.md) |\n\n## Architecture\n\nAI Gateway acts as a proxy between your application and AI providers:\n\n```\nYour App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.)\n ↓\n Analytics, Caching, Rate Limiting, Logging\n```\n\n**Key URL patterns:**\n- Unified API (OpenAI-compatible): `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions`\n- Provider-specific: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}`\n- Dynamic routes: Use route name instead of model: `dynamic/{route-name}`\n\n## Gateway Types\n\n1. **Unauthenticated Gateway**: Open access (not recommended for production)\n2. **Authenticated Gateway**: Requires `cf-aig-authorization` header with Cloudflare API token (recommended)\n\n## Provider Authentication Options\n\n1. **Unified Billing**: Use AI Gateway billing to pay for inference (keyless mode - no provider API key needed)\n2. **BYOK (Store Keys)**: Store provider API keys in Cloudflare dashboard\n3. **Request Headers**: Include provider API key in each request\n\n## Related Skills\n\n- [Workers AI](../workers-ai/README.md) - For `env.AI.run()` details\n- [Agents SDK](../agents-sdk/README.md) - For stateful AI patterns\n- [Vectorize](../vectorize/README.md) - For RAG patterns with embeddings\n\n## Resources\n\n- [Official Docs](https://developers.cloudflare.com/ai-gateway/)\n- [API Reference](https://developers.cloudflare.com/api/resources/ai_gateway/)\n- [Provider Guides](https://developers.cloudflare.com/ai-gateway/usage/providers/)\n- [Discord Community](https://discord.cloudflare.com)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/configuration.md", "content": "# Configuration & Setup\n\n## Creating a Gateway\n\n### Dashboard\nAI > AI Gateway > Create Gateway > Configure (auth, caching, rate limiting, logging)\n\n### API\n```bash\ncurl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \\\n -H \"Authorization: Bearer $CF_API_TOKEN\" -H \"Content-Type: application/json\" \\\n -d '{\"id\":\"my-gateway\",\"cache_ttl\":3600,\"rate_limiting_interval\":60,\"rate_limiting_limit\":100,\"collect_logs\":true}'\n```\n\n**Naming:** lowercase alphanumeric + hyphens (e.g., `prod-api`, `dev-chat`)\n\n## Wrangler Integration\n\n```toml\n[ai]\nbinding = \"AI\"\n\n[[ai.gateway]]\nid = \"my-gateway\"\n```\n\n```bash\nwrangler secret put CF_API_TOKEN\nwrangler secret put OPENAI_API_KEY # If not using BYOK\n```\n\n## Authentication\n\n### Gateway Auth (protects gateway access)\n```typescript\nconst client = new OpenAI({\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` }\n});\n```\n\n### Provider Auth Options\n\n**1. Unified Billing (keyless)** - pay through Cloudflare, no provider key:\n```typescript\nconst client = new OpenAI({\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` }\n});\n```\nSupports: OpenAI, Anthropic, Google AI Studio\n\n**2. BYOK** - store keys in dashboard (Provider Keys > Add), no key in code\n\n**3. Request Headers** - pass provider key per request:\n```typescript\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` }\n});\n```\n\n## API Token Permissions\n\n- **Gateway management:** AI Gateway - Read + Edit\n- **Gateway access:** AI Gateway - Read (minimum)\n\n## Gateway Management API\n\n```bash\n# List\ncurl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \\\n -H \"Authorization: Bearer $CF_API_TOKEN\"\n\n# Get\ncurl .../gateways/{gateway_id}\n\n# Update\ncurl -X PUT .../gateways/{gateway_id} \\\n -d '{\"cache_ttl\":7200,\"rate_limiting_limit\":200}'\n\n# Delete\ncurl -X DELETE .../gateways/{gateway_id}\n```\n\n## Getting IDs\n\n- **Account ID:** Dashboard > Overview > Copy\n- **Gateway ID:** AI Gateway > Gateway name column\n\n## Python Example\n\n```python\nfrom openai import OpenAI\nimport os\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"),\n base_url=f\"https://gateway.ai.cloudflare.com/v1/{os.environ['CF_ACCOUNT_ID']}/{os.environ['GATEWAY_ID']}/openai\",\n default_headers={\"cf-aig-authorization\": f\"Bearer {os.environ['CF_API_TOKEN']}\"}\n)\n```\n\n## Best Practices\n\n1. **Always authenticate gateways in production**\n2. **Use BYOK or unified billing** - secrets out of code\n3. **Environment-specific gateways** - separate dev/staging/prod\n4. **Set rate limits** - prevent runaway costs\n5. **Enable logging** - track usage, debug issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/dynamic-routing.md", "content": "# Dynamic Routing\n\nConfigure complex routing in dashboard without code changes. Use route names instead of model names.\n\n## Usage\n\n```typescript\nconst response = await client.chat.completions.create({\n model: 'dynamic/smart-chat', // Route name from dashboard\n messages: [{ role: 'user', content: 'Hello!' }]\n});\n```\n\n## Node Types\n\n| Node | Purpose | Use Case |\n|------|---------|----------|\n| **Conditional** | Branch on metadata | Paid vs free users, geo routing |\n| **Percentage** | A/B split traffic | Model testing, gradual rollouts |\n| **Rate Limit** | Enforce quotas | Per-user/team limits |\n| **Budget Limit** | Cost quotas | Per-user spending caps |\n| **Model** | Call provider | Final destination |\n\n## Metadata\n\nPass via header (max 5 entries, flat only):\n```typescript\nheaders: {\n 'cf-aig-metadata': JSON.stringify({\n userId: 'user-123',\n tier: 'pro',\n region: 'us-east'\n })\n}\n```\n\n## Common Patterns\n\n**Multi-model fallback:**\n```\nStart → GPT-4 → On error: Claude → On error: Llama\n```\n\n**Tiered access:**\n```\nConditional: tier == 'enterprise' → GPT-4 (no limit)\nConditional: tier == 'pro' → Rate Limit 1000/hr → GPT-4o\nConditional: tier == 'free' → Rate Limit 10/hr → GPT-4o-mini\n```\n\n**Gradual rollout:**\n```\nPercentage: 10% → New model, 90% → Old model\n```\n\n**Cost-based fallback:**\n```\nBudget Limit: $100/day per teamId\n < 80%: GPT-4\n >= 80%: GPT-4o-mini\n >= 100%: Error\n```\n\n## Version Management\n\n- Save changes as new version\n- Test with `model: 'dynamic/route@v2'`\n- Roll back by deploying previous version\n\n## Monitoring\n\nDashboard → Gateway → Dynamic Routes:\n- Request count per path\n- Success/error rates\n- Latency/cost by path\n\n## Limitations\n\n- Max 5 metadata entries\n- Values: string/number/boolean/null only\n- No nested objects\n- Route names: alphanumeric + hyphens\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/features.md", "content": "# Features & Capabilities\n\n## Caching\n\nDashboard: Settings → Cache Responses → Enable\n\n```typescript\n// Custom TTL (1 hour)\nheaders: { 'cf-aig-cache-ttl': '3600' }\n\n// Skip cache\nheaders: { 'cf-aig-skip-cache': 'true' }\n\n// Custom cache key\nheaders: { 'cf-aig-cache-key': 'greeting-en' }\n```\n\n**Limits:** TTL 60s - 30 days. **Does NOT work with streaming.**\n\n## Rate Limiting\n\nDashboard: Settings → Rate-limiting → Enable\n\n- **Fixed window:** Resets at intervals\n- **Sliding window:** Rolling window (more accurate)\n- Returns `429` when exceeded\n\n## Guardrails\n\nDashboard: Settings → Guardrails → Enable\n\nFilter prompts/responses for inappropriate content. Actions: Flag (log) or Block (reject).\n\n## Data Loss Prevention (DLP)\n\nDashboard: Settings → DLP → Enable\n\nDetect PII (emails, SSNs, credit cards). Actions: Flag, Block, or Redact.\n\n## Billing Modes\n\n| Mode | Description | Setup |\n|------|-------------|-------|\n| **Unified Billing** | Pay through Cloudflare, no provider keys | Use `cf-aig-authorization` header only |\n| **BYOK** | Store provider keys in dashboard | Add keys in Provider Keys section |\n| **Pass-through** | Send provider key with each request | Include provider's auth header |\n\n## Zero Data Retention\n\nDashboard: Settings → Privacy → Zero Data Retention\n\nNo prompts/responses stored. Request counts and costs still tracked.\n\n## Logging\n\nDashboard: Settings → Logs → Enable (up to 10M logs)\n\nEach entry: prompt, response, provider, model, tokens, cost, duration, cache status, metadata.\n\n```typescript\n// Skip logging for request\nheaders: { 'cf-aig-collect-log': 'false' }\n```\n\n**Export:** Use Logpush to S3, GCS, Datadog, Splunk, etc.\n\n## Custom Cost Tracking\n\nFor models not in Cloudflare's pricing database:\n\nDashboard: Gateway → Settings → Custom Costs\n\nOr via API: set `model`, `input_cost`, `output_cost`.\n\n## Supported Providers (22+)\n\n| Provider | Unified API | Notes |\n|----------|-------------|-------|\n| OpenAI | `openai/gpt-4o` | Full support |\n| Anthropic | `anthropic/claude-sonnet-4-5` | Full support |\n| Google AI | `google-ai-studio/gemini-2.0-flash` | Full support |\n| Workers AI | `workersai/@cf/meta/llama-3` | Native |\n| Azure OpenAI | `azure-openai/*` | Deployment names |\n| AWS Bedrock | Provider endpoint only | `/bedrock/*` |\n| Groq | `groq/*` | Fast inference |\n| Mistral, Cohere, Perplexity, xAI, DeepSeek, Cerebras | Full support | - |\n\n## Best Practices\n\n1. Enable caching for deterministic prompts\n2. Set rate limits to prevent abuse\n3. Use guardrails for user-facing AI\n4. Enable DLP for sensitive data\n5. Use unified billing or BYOK for simpler key management\n6. Enable logging for debugging\n7. Use zero data retention when privacy required\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/sdk-integration.md", "content": "# AI Gateway SDK Integration\n\n## Vercel AI SDK (Recommended)\n\n```typescript\nimport { createAiGateway } from 'ai-gateway-provider';\nimport { createOpenAI } from '@ai-sdk/openai';\nimport { generateText } from 'ai';\n\nconst gateway = createAiGateway({\n accountId: process.env.CF_ACCOUNT_ID,\n gateway: process.env.CF_GATEWAY_ID,\n apiKey: process.env.CF_API_TOKEN // Optional for auth gateways\n});\n\nconst openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });\n\n// Single model\nconst { text } = await generateText({\n model: gateway(openai('gpt-4o')),\n prompt: 'Hello'\n});\n\n// Automatic fallback array\nconst { text } = await generateText({\n model: gateway([\n openai('gpt-4o'),\n anthropic('claude-sonnet-4-5'),\n openai('gpt-4o-mini')\n ]),\n prompt: 'Complex task'\n});\n```\n\n### Options\n\n```typescript\nmodel: gateway(openai('gpt-4o'), {\n cacheKey: 'my-key',\n cacheTtl: 3600,\n metadata: { userId: 'u123', team: 'eng' }, // Max 5 entries\n retries: { maxAttempts: 3, backoff: 'exponential' }\n})\n```\n\n## OpenAI SDK\n\n```typescript\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` }\n});\n\n// Unified API - switch providers via model name\nmodel: 'openai/gpt-4o' // or 'anthropic/claude-sonnet-4-5'\n```\n\n## Anthropic SDK\n\n```typescript\nconst client = new Anthropic({\n apiKey: process.env.ANTHROPIC_API_KEY,\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/anthropic`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` }\n});\n```\n\n## Workers AI Binding\n\n```toml\n# wrangler.toml\n[ai]\nbinding = \"AI\"\n[[ai.gateway]]\nid = \"my-gateway\"\n```\n\n```typescript\nawait env.AI.run('@cf/meta/llama-3-8b-instruct', \n { messages: [...] },\n { gateway: { id: 'my-gateway', metadata: { userId: '123' } } }\n);\n```\n\n## LangChain / LlamaIndex\n\n```typescript\n// Use OpenAI SDK pattern with custom baseURL\nnew ChatOpenAI({\n configuration: {\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`\n }\n});\n```\n\n## HTTP / cURL\n\n```bash\ncurl https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/chat/completions \\\n -H \"Authorization: Bearer $OPENAI_KEY\" \\\n -H \"cf-aig-authorization: Bearer $CF_TOKEN\" \\\n -H \"cf-aig-metadata: {\\\"userId\\\":\\\"123\\\"}\" \\\n -d '{\"model\":\"gpt-4o\",\"messages\":[...]}'\n```\n\n## Headers Reference\n\n| Header | Purpose |\n|--------|---------|\n| `cf-aig-authorization` | Gateway auth token |\n| `cf-aig-metadata` | JSON object (max 5 keys) |\n| `cf-aig-cache-ttl` | Cache TTL in seconds |\n| `cf-aig-skip-cache` | `true` to bypass cache |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-gateway/troubleshooting.md", "content": "# AI Gateway Troubleshooting\n\n## Common Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| 401 | Missing `cf-aig-authorization` header | Add header with CF API token |\n| 403 | Invalid provider key / BYOK expired | Check provider key in dashboard |\n| 429 | Rate limit exceeded | Increase limit or implement backoff |\n\n### 401 Fix\n\n```typescript\nconst client = new OpenAI({\n baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,\n defaultHeaders: { 'cf-aig-authorization': `Bearer ${CF_API_TOKEN}` }\n});\n```\n\n### 429 Retry Pattern\n\n```typescript\nasync function requestWithRetry(fn, maxRetries = 3) {\n for (let i = 0; i < maxRetries; i++) {\n try { return await fn(); }\n catch (e) {\n if (e.status === 429 && i < maxRetries - 1) {\n await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));\n continue;\n }\n throw e;\n }\n }\n}\n```\n\n## Gotchas\n\n| Issue | Reality |\n|-------|---------|\n| Metadata limits | Max 5 entries, flat only (no nesting) |\n| Cache key collision | Use unique keys per expected response |\n| BYOK + Unified Billing | Mutually exclusive |\n| Rate limit scope | Per-gateway, not per-user (use dynamic routing for per-user) |\n| Log delay | 30-60 seconds normal |\n| Streaming + caching | **Incompatible** |\n| Model name (unified API) | Prefix required: `openai/gpt-4o`, not `gpt-4o` |\n\n## Cache Not Working\n\n**Causes:**\n- Different request params (temperature, etc.)\n- Streaming enabled\n- Caching disabled in settings\n\n**Check:** `response.headers.get('cf-aig-cache-status')` → HIT or MISS\n\n## Logs Not Appearing\n\n1. Check logging enabled: Dashboard → Gateway → Settings\n2. Remove `cf-aig-collect-log: false` header\n3. Wait 30-60 seconds\n4. Check log limit (10M default)\n\n## Debugging\n\n```bash\n# Test connectivity\ncurl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \\\n -H \"Authorization: Bearer $OPENAI_KEY\" \\\n -H \"cf-aig-authorization: Bearer $CF_TOKEN\"\n```\n\n```typescript\n// Check response headers\nconsole.log('Cache:', response.headers.get('cf-aig-cache-status'));\nconsole.log('Request ID:', response.headers.get('cf-ray'));\n```\n\n## Analytics\n\nDashboard → AI Gateway → Select gateway\n\n**Metrics:** Requests, tokens, latency (p50/p95/p99), cache hit rate, costs\n\n**Log filters:** `status: error`, `provider: openai`, `cost > 0.01`, `duration > 1000`\n\n**Export:** Logpush to S3/GCS/Datadog/Splunk\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-search/README.md", "content": "# Cloudflare AI Search Reference\n\nExpert guidance for implementing Cloudflare AI Search (formerly AutoRAG), Cloudflare's managed semantic search and RAG service.\n\n## Overview\n\n**AI Search** is a managed RAG (Retrieval-Augmented Generation) pipeline that combines:\n- Automatic semantic indexing of your content\n- Vector similarity search\n- Built-in LLM generation\n\n**Key value propositions:**\n- **Zero vector management** - No manual embedding, indexing, or storage\n- **Auto-indexing** - Content automatically re-indexed every 6 hours\n- **Built-in generation** - Optional AI response generation from retrieved context\n- **Multi-source** - Index from R2 buckets or website crawls\n\n**Data source options:**\n- **R2 bucket** - Index files from Cloudflare R2 (supports MD, TXT, HTML, PDF, DOC, CSV, JSON)\n- **Website** - Crawl and index website content (requires Cloudflare-hosted domain)\n\n**Indexing lifecycle:**\n- Automatic 6-hour refresh cycle\n- Manual \"Force Sync\" available (30s rate limit)\n- Not designed for real-time updates\n\n## Quick Start\n\n**1. Create AI Search instance in dashboard:**\n- Go to Cloudflare Dashboard → AI Search → Create\n- Choose data source (R2 or website)\n- Configure instance name and settings\n\n**2. Configure Worker:**\n\n```jsonc\n// wrangler.jsonc\n{\n \"ai\": {\n \"binding\": \"AI\"\n }\n}\n```\n\n**3. Use in Worker:**\n\n```typescript\nexport default {\n async fetch(request, env) {\n const answer = await env.AI.autorag(\"my-search-instance\").aiSearch({\n query: \"How do I configure caching?\",\n model: \"@cf/meta/llama-3.3-70b-instruct-fp8-fast\"\n });\n \n return Response.json({ answer: answer.response });\n }\n};\n```\n\n## When to Use AI Search\n\n### AI Search vs Vectorize\n\n| Factor | AI Search | Vectorize |\n|--------|-----------|-----------|\n| **Management** | Fully managed | Manual embedding + indexing |\n| **Use when** | Want zero-ops RAG pipeline | Need custom embeddings/control |\n| **Indexing** | Automatic (6hr cycle) | Manual via API |\n| **Generation** | Built-in optional | Bring your own LLM |\n| **Data sources** | R2 or website | Manual insert |\n| **Best for** | Docs, support, enterprise search | Custom ML pipelines, real-time |\n\n### AI Search vs Direct Workers AI\n\n| Factor | AI Search | Workers AI (direct) |\n|--------|-----------|---------------------|\n| **Context** | Automatic retrieval | Manual context building |\n| **Use when** | Need RAG (search + generate) | Simple generation tasks |\n| **Indexing** | Built-in | Not applicable |\n| **Best for** | Knowledge bases, docs | Simple chat, transformations |\n\n### search() vs aiSearch()\n\n| Method | Returns | Use When |\n|--------|---------|----------|\n| `search()` | Search results only | Building custom UI, need raw chunks |\n| `aiSearch()` | AI response + results | Need ready-to-use answer (chatbot, Q&A) |\n\n### Real-time Updates Consideration\n\n**AI Search is NOT ideal if:**\n- Need real-time content updates (<6 hours)\n- Content changes multiple times per hour\n- Strict freshness requirements\n\n**AI Search IS ideal if:**\n- Content relatively stable (docs, policies, knowledge bases)\n- 6-hour refresh acceptable\n- Prefer zero-ops over real-time\n\n## Platform Limits\n\n| Limit | Value |\n|-------|-------|\n| Max instances per account | 10 |\n| Max files per instance | 100,000 |\n| Max file size | 4 MB |\n| Index frequency | Every 6 hours |\n| Force Sync rate limit | Once per 30 seconds |\n| Filter nesting depth | 2 levels |\n| Filters per compound | 10 |\n| Score threshold range | 0.0 - 1.0 |\n\n## Reading Order\n\nNavigate these references based on your task:\n\n| Task | Read | Est. Time |\n|------|------|-----------|\n| **Understand AI Search** | README only | 5 min |\n| **Implement basic search** | README → api.md | 10 min |\n| **Configure data source** | README → configuration.md | 10 min |\n| **Production patterns** | patterns.md | 15 min |\n| **Debug issues** | gotchas.md | 10 min |\n| **Full implementation** | README → api.md → patterns.md | 30 min |\n\n## In This Reference\n\n- **[api.md](api.md)** - API endpoints, methods, TypeScript interfaces\n- **[configuration.md](configuration.md)** - Setup, data sources, wrangler config\n- **[patterns.md](patterns.md)** - Common patterns, decision guidance, code examples\n- **[gotchas.md](gotchas.md)** - Troubleshooting, code-level gotchas, limits\n\n## See Also\n\n- [Cloudflare AI Search Docs](https://developers.cloudflare.com/ai-search/)\n- [Workers AI Docs](https://developers.cloudflare.com/workers-ai/)\n- [Vectorize Docs](https://developers.cloudflare.com/vectorize/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-search/api.md", "content": "# AI Search API Reference\n\n## Workers Binding\n\n```typescript\nconst answer = await env.AI.autorag(\"instance-name\").aiSearch(options);\nconst results = await env.AI.autorag(\"instance-name\").search(options);\nconst instances = await env.AI.autorag(\"_\").listInstances();\n```\n\n## aiSearch() Options\n\n```typescript\ninterface AiSearchOptions {\n query: string; // User query\n model: string; // Workers AI model ID\n system_prompt?: string; // LLM instructions\n rewrite_query?: boolean; // Fix typos (default: false)\n max_num_results?: number; // Max chunks (default: 10)\n ranking_options?: { score_threshold?: number }; // 0.0-1.0 (default: 0.3)\n reranking?: { enabled: boolean; model: string };\n stream?: boolean; // Stream response (default: false)\n filters?: Filter; // Metadata filters\n page?: string; // Pagination token\n}\n```\n\n## Response\n\n```typescript\ninterface AiSearchResponse {\n search_query: string; // Query used (rewritten if enabled)\n response: string; // AI-generated answer\n data: SearchResult[]; // Retrieved chunks\n has_more: boolean;\n next_page?: string;\n}\n\ninterface SearchResult {\n id: string;\n score: number;\n content: string;\n metadata: { filename: string; folder: string; timestamp: number };\n}\n```\n\n## Filters\n\n```typescript\n// Comparison\n{ column: \"folder\", operator: \"gte\", value: \"docs/\" }\n\n// Compound\n{ operator: \"and\", filters: [\n { column: \"folder\", operator: \"gte\", value: \"docs/\" },\n { column: \"timestamp\", operator: \"gte\", value: 1704067200 }\n]}\n```\n\n**Operators:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`\n\n**Built-in metadata:** `filename`, `folder`, `timestamp` (Unix seconds)\n\n## Streaming\n\n```typescript\nconst stream = await env.AI.autorag(\"docs\").aiSearch({ query, model, stream: true });\nreturn new Response(stream, { headers: { \"Content-Type\": \"text/event-stream\" } });\n```\n\n## Error Types\n\n| Error | Cause |\n|-------|-------|\n| `AutoRAGNotFoundError` | Instance doesn't exist |\n| `AutoRAGUnauthorizedError` | Invalid/missing token |\n| `AutoRAGValidationError` | Invalid parameters |\n\n## REST API\n\n```bash\ncurl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{NAME}/ai-search \\\n -H \"Authorization: Bearer {TOKEN}\" \\\n -d '{\"query\": \"...\", \"model\": \"@cf/meta/llama-3.3-70b-instruct-fp8-fast\"}'\n```\n\nRequires Service API token with \"AI Search - Read\" permission.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-search/configuration.md", "content": "# AI Search Configuration\n\n## Worker Setup\n\n```jsonc\n// wrangler.jsonc\n{\n \"ai\": { \"binding\": \"AI\" }\n}\n```\n\n```typescript\ninterface Env {\n AI: Ai;\n}\n\nconst answer = await env.AI.autorag(\"my-instance\").aiSearch({\n query: \"How do I configure caching?\",\n model: \"@cf/meta/llama-3.3-70b-instruct-fp8-fast\"\n});\n```\n\n## Data Sources\n\n### R2 Bucket\n\nDashboard: AI Search → Create Instance → Select R2 bucket\n\n**Supported formats:** `.md`, `.txt`, `.html`, `.pdf`, `.doc`, `.docx`, `.csv`, `.json`\n\n**Auto-indexed metadata:** `filename`, `folder`, `timestamp`\n\n### Website Crawler\n\nRequirements:\n- Domain on Cloudflare\n- `sitemap.xml` at root\n- Bot protection must allow `CloudflareAISearch` user agent\n\n## Path Filtering (R2)\n\n```\ndocs/**/*.md # All .md in docs/ recursively\n**/*.draft.md # Exclude (use in exclude patterns)\n```\n\n## Indexing\n\n- **Automatic:** Every 6 hours\n- **Force Sync:** Dashboard button (30s rate limit between syncs)\n- **Pause:** Settings → Pause Indexing (existing index remains searchable)\n\n## Service API Token\n\nDashboard: AI Search → Instance → Use AI Search → API → Create Token\n\nPermissions:\n- **Read** - search operations\n- **Edit** - instance management\n\nStore securely:\n```bash\nwrangler secret put AI_SEARCH_TOKEN\n```\n\n## Multi-Environment\n\n```toml\n# wrangler.toml\n[env.production.vars]\nAI_SEARCH_INSTANCE = \"prod-docs\"\n\n[env.staging.vars]\nAI_SEARCH_INSTANCE = \"staging-docs\"\n```\n\n```typescript\nconst answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({ query });\n```\n\n## Monitoring\n\n```typescript\nconst instances = await env.AI.autorag(\"_\").listInstances();\nconsole.log(instances.find(i => i.name === \"docs\"));\n```\n\nDashboard shows: files indexed, status, last index time, storage usage.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-search/gotchas.md", "content": "# AI Search Gotchas\n\n## Type Safety\n\n**Timestamp precision:** Use seconds (10-digit), not milliseconds.\n```typescript\nconst nowInSeconds = Math.floor(Date.now() / 1000); // Correct\n```\n\n**Folder prefix matching:** Use `gte` for \"starts with\" on paths.\n```typescript\nfilters: { column: \"folder\", operator: \"gte\", value: \"docs/api/\" } // Matches nested\n```\n\n## Filter Limitations\n\n| Limit | Value |\n|-------|-------|\n| Max nesting depth | 2 levels |\n| Filters per compound | 10 |\n| `or` operator | Same column, `eq` only |\n\n**OR restriction example:**\n```typescript\n// ✅ Valid: same column, eq only\n{ operator: \"or\", filters: [\n { column: \"folder\", operator: \"eq\", value: \"docs/\" },\n { column: \"folder\", operator: \"eq\", value: \"guides/\" }\n]}\n```\n\n## Indexing Issues\n\n| Problem | Cause | Solution |\n|---------|-------|----------|\n| File not indexed | Unsupported format or >4MB | Check format (.md/.txt/.html/.pdf/.doc/.csv/.json) |\n| Index out of sync | 6-hour index cycle | Wait or use \"Force Sync\" (30s rate limit) |\n| Empty results | Index incomplete | Check dashboard for indexing status |\n\n## Auth Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `AutoRAGUnauthorizedError` | Invalid/missing token | Create Service API token with AI Search permissions |\n| `AutoRAGNotFoundError` | Wrong instance name | Verify exact name from dashboard |\n\n## Performance\n\n**Slow responses (>3s):**\n```typescript\n// Add score threshold + limit results\nranking_options: { score_threshold: 0.5 },\nmax_num_results: 10\n```\n\n**Empty results debug:**\n1. Remove filters, test basic query\n2. Lower `score_threshold` to 0.1\n3. Check index is populated\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Instances per account | 10 |\n| Files per instance | 100,000 |\n| Max file size | 4 MB |\n| Index frequency | 6 hours |\n\n## Anti-Patterns\n\n**Use env vars for instance names:**\n```typescript\nconst answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...});\n```\n\n**Handle specific error types:**\n```typescript\nif (error instanceof AutoRAGNotFoundError) { /* 404 */ }\nif (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ai-search/patterns.md", "content": "# AI Search Patterns\n\n## search() vs aiSearch()\n\n| Use | Method | Returns |\n|-----|--------|---------|\n| Custom UI, analytics | `search()` | Raw chunks only (~100-300ms) |\n| Chatbots, Q&A | `aiSearch()` | AI response + chunks (~500-2000ms) |\n\n## rewrite_query\n\n| Setting | Use When |\n|---------|----------|\n| `true` | User input (typos, vague queries) |\n| `false` | LLM-generated queries (already optimized) |\n\n## Multitenancy (Folder-Based)\n\n```typescript\nconst answer = await env.AI.autorag(\"saas-docs\").aiSearch({\n query: \"refund policy\",\n model: \"@cf/meta/llama-3.3-70b-instruct-fp8-fast\",\n filters: {\n column: \"folder\",\n operator: \"gte\", // \"starts with\" pattern\n value: `tenants/${tenantId}/`\n }\n});\n```\n\n## Streaming\n\n```typescript\nconst stream = await env.AI.autorag(\"docs\").aiSearch({\n query, model: \"@cf/meta/llama-3.3-70b-instruct-fp8-fast\", stream: true\n});\nreturn new Response(stream, { headers: { \"Content-Type\": \"text/event-stream\" } });\n```\n\n## Score Threshold\n\n| Threshold | Use |\n|-----------|-----|\n| 0.3 (default) | Broad recall, exploratory |\n| 0.5 | Balanced, production default |\n| 0.7 | High precision, critical accuracy |\n\n## System Prompt Template\n\n```typescript\nconst systemPrompt = `You are a documentation assistant.\n- Answer ONLY based on provided context\n- If context doesn't contain answer, say \"I don't have information\"\n- Include code examples from context`;\n```\n\n## Compound Filters\n\n```typescript\n// OR: Multiple folders\nfilters: {\n operator: \"or\",\n filters: [\n { column: \"folder\", operator: \"gte\", value: \"docs/api/\" },\n { column: \"folder\", operator: \"gte\", value: \"docs/auth/\" }\n ]\n}\n\n// AND: Folder + date\nfilters: {\n operator: \"and\",\n filters: [\n { column: \"folder\", operator: \"gte\", value: \"docs/\" },\n { column: \"timestamp\", operator: \"gte\", value: oneWeekAgoSeconds }\n ]\n}\n```\n\n## Reranking\n\nEnable for high-stakes use cases (adds ~300ms latency):\n\n```typescript\nreranking: { enabled: true, model: \"@cf/baai/bge-reranker-base\" }\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/analytics-engine/README.md", "content": "# Cloudflare Workers Analytics Engine Reference\n\nExpert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.\n\n## What is Analytics Engine?\n\nTime-series analytics database designed for high-cardinality data (millions of unique dimensions). Write data points from Workers, query via SQL API. Use for:\n- Custom user-facing analytics dashboards\n- Usage-based billing & metering\n- Per-customer/per-feature monitoring\n- High-frequency instrumentation without performance impact\n\n**Key Capability:** Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.\n\n## Core Concepts\n\n| Concept | Description | Example |\n|---------|-------------|---------|\n| **Dataset** | Logical table for related metrics | `api_requests`, `user_events` |\n| **Data Point** | Single measurement with timestamp | One API request's metrics |\n| **Blobs** | String dimensions (max 20) | endpoint, method, status, user_id |\n| **Doubles** | Numeric values (max 20) | latency_ms, request_count, bytes |\n| **Indexes** | Filtered blobs for efficient queries | customer_id, api_key |\n\n## Reading Order\n\n| Task | Start Here | Then Read |\n|------|------------|-----------|\n| **First-time setup** | [configuration.md](configuration.md) → [api.md](api.md) → [patterns.md](patterns.md) | |\n| **Writing data** | [api.md](api.md) → [gotchas.md](gotchas.md) (sampling) | |\n| **Querying data** | [api.md](api.md) (SQL API) → [patterns.md](patterns.md) (examples) | |\n| **Debugging** | [gotchas.md](gotchas.md) → [api.md](api.md) (limits) | |\n| **Optimization** | [patterns.md](patterns.md) (anti-patterns) → [gotchas.md](gotchas.md) | |\n\n## When to Use Analytics Engine\n\n```\nNeed to track metrics? → Yes\n ↓\nMillions of unique dimension values? → Yes\n ↓\n Need real-time queries? → Yes\n ↓\n Use Analytics Engine ✓\n\nAlternative scenarios:\n- Low cardinality (<10k unique values) → Workers Analytics (free tier)\n- Complex joins/relations → D1 Database\n- Logs/debugging → Tail Workers (logpush)\n- External tools → Send to external analytics (Datadog, etc.)\n```\n\n## Quick Start\n\n1. Add binding to `wrangler.jsonc`:\n```jsonc\n{\n \"analytics_engine_datasets\": [\n { \"binding\": \"ANALYTICS\", \"dataset\": \"my_events\" }\n ]\n}\n```\n\n2. Write data points (fire-and-forget, no await):\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [\"/api/users\", \"GET\", \"200\"],\n doubles: [145.2, 1], // latency_ms, count\n indexes: [customerId]\n});\n```\n\n3. Query via SQL API (HTTP):\n```sql\nSELECT blob1, SUM(double2) AS total_requests\nFROM my_events\nWHERE index1 = 'customer_123'\n AND timestamp >= NOW() - INTERVAL '7' DAY\nGROUP BY blob1\nORDER BY total_requests DESC\n```\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, bindings, TypeScript types, limits\n- **[api.md](api.md)** - `writeDataPoint()`, SQL API, query syntax\n- **[patterns.md](patterns.md)** - Use cases, examples, anti-patterns\n- **[gotchas.md](gotchas.md)** - Sampling, index selection, troubleshooting\n\n## See Also\n\n- [Cloudflare Analytics Engine Docs](https://developers.cloudflare.com/analytics/analytics-engine/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/analytics-engine/api.md", "content": "# Analytics Engine API Reference\n\n## Writing Data\n\n### `writeDataPoint()`\n\nFire-and-forget (returns `void`, not Promise). Writes happen asynchronously.\n\n```typescript\ninterface AnalyticsEngineDataPoint {\n blobs?: string[]; // Up to 20 strings (dimensions), 16KB each\n doubles?: number[]; // Up to 20 numbers (metrics)\n indexes?: string[]; // 1 indexed string for high-cardinality filtering\n}\n\nenv.ANALYTICS.writeDataPoint({\n blobs: [\"/api/users\", \"GET\", \"200\"],\n doubles: [145.2, 1], // latency_ms, count\n indexes: [\"customer_abc123\"]\n});\n```\n\n**Behaviors:** No await needed, no error thrown (check tail logs), auto-sampled at high volumes, auto-timestamped.\n\n**Blob vs Index:** Blob for GROUP BY (<100k unique), Index for filter-only (millions unique).\n\n### Full Example\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const start = Date.now();\n const url = new URL(request.url);\n try {\n const response = await handleRequest(request);\n env.ANALYTICS.writeDataPoint({\n blobs: [url.pathname, request.method, response.status.toString()],\n doubles: [Date.now() - start, 1],\n indexes: [request.headers.get(\"x-api-key\") || \"anonymous\"]\n });\n return response;\n } catch (error) {\n env.ANALYTICS.writeDataPoint({\n blobs: [url.pathname, request.method, \"500\"],\n doubles: [Date.now() - start, 1, 0],\n });\n throw error;\n }\n }\n};\n```\n\n## SQL API (External Only)\n\n```bash\ncurl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d \"SELECT blob1 AS endpoint, COUNT(*) AS requests FROM dataset WHERE timestamp >= NOW() - INTERVAL '1' HOUR GROUP BY blob1\"\n```\n\n### Column References\n\n```sql\n-- blob1..blob20, double1..double20, index1, timestamp\nSELECT blob1 AS endpoint, SUM(double1) AS latency, COUNT(*) AS requests\nFROM my_dataset\nWHERE index1 = 'customer_123' AND timestamp >= NOW() - INTERVAL '7' DAY\nGROUP BY blob1\nHAVING COUNT(*) > 100\nORDER BY requests DESC LIMIT 100\n```\n\n**Aggregations:** `SUM()`, `AVG()`, `COUNT()`, `MIN()`, `MAX()`, `quantile(0.95)()`\n\n**Time ranges:** `NOW() - INTERVAL '1' HOUR`, `BETWEEN '2026-01-01' AND '2026-01-31'`\n\n### Query Examples\n\n```sql\n-- Top endpoints\nSELECT blob1, COUNT(*) AS requests, AVG(double1) AS avg_latency\nFROM api_requests WHERE timestamp >= NOW() - INTERVAL '24' HOUR\nGROUP BY blob1 ORDER BY requests DESC LIMIT 20\n\n-- Error rate\nSELECT blob1, COUNT(*) AS total,\n SUM(CASE WHEN blob3 LIKE '5%' THEN 1 ELSE 0 END) AS errors\nFROM api_requests WHERE timestamp >= NOW() - INTERVAL '1' HOUR\nGROUP BY blob1 HAVING total > 50\n\n-- P95 latency\nSELECT blob1, quantile(0.95)(double1) AS p95\nFROM api_requests GROUP BY blob1\n```\n\n## Response Format\n\n```json\n{\"data\": [{\"endpoint\": \"/api/users\", \"requests\": 1523}], \"rows\": 2}\n```\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Blobs/Doubles per point | 20 each |\n| Indexes per point | 1 |\n| Blob/Index size | 16KB |\n| Data retention | 90 days |\n| Query timeout | 30s |\n\n**Critical:** High write volumes (>1M/min) trigger automatic sampling.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/analytics-engine/configuration.md", "content": "# Analytics Engine Configuration\n\n## Setup\n\n1. Add binding to `wrangler.jsonc`\n2. Deploy Worker\n3. Dataset created automatically on first write\n4. Query via SQL API\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"analytics_engine_datasets\": [\n { \"binding\": \"ANALYTICS\", \"dataset\": \"my_events\" }\n ]\n}\n```\n\nMultiple datasets for separate concerns:\n```jsonc\n{\n \"analytics_engine_datasets\": [\n { \"binding\": \"API_ANALYTICS\", \"dataset\": \"api_requests\" },\n { \"binding\": \"USER_EVENTS\", \"dataset\": \"user_activity\" }\n ]\n}\n```\n\n## TypeScript\n\n```typescript\ninterface Env {\n ANALYTICS: AnalyticsEngineDataset;\n}\n\nexport default {\n async fetch(request: Request, env: Env) {\n // No await - returns void, fire-and-forget\n env.ANALYTICS.writeDataPoint({\n blobs: [pathname, method, status], // String dimensions (max 20)\n doubles: [latency, 1], // Numeric metrics (max 20)\n indexes: [apiKey] // High-cardinality filter (max 1)\n });\n return response;\n }\n};\n```\n\n## Data Point Limits\n\n| Field | Limit | SQL Access |\n|-------|-------|------------|\n| blobs | 20 strings, 16KB each | `blob1`...`blob20` |\n| doubles | 20 numbers | `double1`...`double20` |\n| indexes | 1 string, 16KB | `index1` |\n\n## Write Behavior\n\n| Scenario | Behavior |\n|----------|----------|\n| <1M writes/min | All accepted |\n| >1M writes/min | Automatic sampling |\n| Invalid data | Silent failure (check tail logs) |\n\n**Mitigate sampling:** Pre-aggregate, use multiple datasets, write only critical metrics.\n\n## Query Limits\n\n| Resource | Limit |\n|----------|-------|\n| Query timeout | 30 seconds |\n| Data retention | 90 days (default) |\n| Result size | ~10MB |\n\n## Cost\n\n**Free tier:** 10M writes/month, 1M reads/month\n\n**Paid:** $0.05 per 1M writes, $1.00 per 1M reads\n\n## Environment-Specific\n\n```jsonc\n{\n \"analytics_engine_datasets\": [\n { \"binding\": \"ANALYTICS\", \"dataset\": \"prod_events\" }\n ],\n \"env\": {\n \"staging\": {\n \"analytics_engine_datasets\": [\n { \"binding\": \"ANALYTICS\", \"dataset\": \"staging_events\" }\n ]\n }\n }\n}\n```\n\n## Monitoring\n\n```bash\nnpx wrangler tail # Check for sampling/write errors\n```\n\n```sql\n-- Check write activity\nSELECT DATE_TRUNC('hour', timestamp) AS hour, COUNT(*) AS writes\nFROM my_dataset\nWHERE timestamp >= NOW() - INTERVAL '24' HOUR\nGROUP BY hour\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/analytics-engine/gotchas.md", "content": "# Analytics Engine Gotchas\n\n## Critical Issues\n\n### Sampling at High Volumes\n\n**Problem:** Queries return fewer points than written at >1M writes/min.\n\n**Solution:**\n```typescript\n// Pre-aggregate before writing\nlet buffer = { count: 0, total: 0 };\nbuffer.count++; buffer.total += value;\n\n// Write once per second instead of per request\nif (Date.now() % 1000 === 0) {\n env.ANALYTICS.writeDataPoint({ doubles: [buffer.count, buffer.total] });\n}\n```\n\n**Detection:** `npx wrangler tail` → look for \"sampling enabled\"\n\n### writeDataPoint Returns void\n\n```typescript\n// ❌ Pointless await\nawait env.ANALYTICS.writeDataPoint({...});\n\n// ✅ Fire-and-forget\nenv.ANALYTICS.writeDataPoint({...});\n```\n\nWrites can fail silently. Check tail logs.\n\n### Index vs Blob\n\n| Cardinality | Use | Example |\n|-------------|-----|---------|\n| Millions | **Index** | user_id, api_key |\n| Hundreds | **Blob** | endpoint, status_code, country |\n\n```typescript\n// ✅ Correct\n{ blobs: [method, path, status], indexes: [userId] }\n```\n\n### Can't Query from Workers\n\nQuery API requires HTTP auth. Use external service or cache in KV/D1.\n\n### No Custom Timestamps\n\nAuto-generated at write time. Store original in blob if needed.\n\n## Common Errors\n\n| Error | Fix |\n|-------|-----|\n| Binding not found | Check wrangler.jsonc, redeploy |\n| No data in query | Wait 30s; check dataset name; check time range |\n| Query timeout | Add time filter; use index for filtering |\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Blobs per point | 20 |\n| Doubles per point | 20 |\n| Indexes per point | 1 |\n| Blob/Index size | 16KB |\n| Write rate (no sampling) | ~1M/min |\n| Retention | 90 days |\n| Query timeout | 30s |\n\n## Best Practices\n\n✅ Pre-aggregate at high volumes \n✅ Use index for high-cardinality (millions) \n✅ Always include time filter in queries \n✅ Design schema before coding \n\n❌ Don't await writeDataPoint \n❌ Don't use index for low-cardinality \n❌ Don't query without time range \n❌ Don't assume all writes succeed\n" }, { "path": "skills/.curated/cloudflare-deploy/references/analytics-engine/patterns.md", "content": "# Analytics Engine Patterns\n\n## Use Cases\n\n| Use Case | Key Metrics | Index On |\n|----------|-------------|----------|\n| API Metering | requests, bytes, compute_units | api_key |\n| Feature Usage | feature, action, duration | user_id |\n| Error Tracking | error_type, endpoint, count | customer_id |\n| Performance | latency_ms, cache_status | endpoint |\n| A/B Testing | variant, conversions | user_id |\n\n## API Metering (Billing)\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [pathname, method, status, tier],\n doubles: [1, computeUnits, bytes, latencyMs],\n indexes: [apiKey]\n});\n\n// Query: Monthly usage by customer\n// SELECT index1 AS api_key, SUM(double2) AS compute_units\n// FROM usage WHERE timestamp >= DATE_TRUNC('month', NOW()) GROUP BY index1\n```\n\n## Error Tracking\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [endpoint, method, errorName, errorMessage.slice(0, 1000)],\n doubles: [1, timeToErrorMs],\n indexes: [customerId]\n});\n```\n\n## Performance Monitoring\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [pathname, method, cacheStatus, status],\n doubles: [latencyMs, 1],\n indexes: [userId]\n});\n\n// Query: P95 latency by endpoint\n// SELECT blob1, quantile(0.95)(double1) AS p95_ms FROM perf GROUP BY blob1\n```\n\n## Anti-Patterns\n\n| ❌ Wrong | ✅ Correct |\n|----------|-----------|\n| `await writeDataPoint()` | `writeDataPoint()` (fire-and-forget) |\n| `indexes: [method]` (low cardinality) | `blobs: [method]`, `indexes: [userId]` |\n| `blobs: [JSON.stringify(obj)]` | Store ID in blob, full object in D1/KV |\n| Write every request at 10M/min | Pre-aggregate per second |\n| Query from Worker | Query from external service/API |\n\n## Best Practices\n\n1. **Design schema upfront** - Document blob/double/index assignments\n2. **Always include count metric** - `doubles: [latency, 1]` for AVG calculations\n3. **Use enums for blobs** - Consistent values like `Status.SUCCESS`\n4. **Handle sampling** - Use ratios (avg_latency = SUM(latency)/SUM(count))\n5. **Test queries early** - Validate schema before heavy writes\n\n## Schema Template\n\n```typescript\n/**\n * Dataset: my_metrics\n * \n * Blobs:\n * blob1: endpoint, blob2: method, blob3: status\n * \n * Doubles:\n * double1: latency_ms, double2: count (always 1)\n * \n * Indexes:\n * index1: customer_id (high cardinality)\n */\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api/README.md", "content": "# Cloudflare API Integration\n\nGuide for working with Cloudflare's REST API - authentication, SDK usage, common patterns, and troubleshooting.\n\n## Quick Decision Tree\n\n```\nHow are you calling the Cloudflare API?\n├─ From Workers runtime → Use bindings, not REST API (see ../bindings/)\n├─ Server-side (Node/Python/Go) → Official SDK (see api.md)\n├─ CLI/scripts → Wrangler or curl (see configuration.md)\n├─ Infrastructure-as-code → See ../pulumi/ or ../terraform/\n└─ One-off requests → curl examples (see api.md)\n```\n\n## SDK Selection\n\n| Language | Package | Best For | Default Retries |\n|----------|---------|----------|-----------------|\n| TypeScript | `cloudflare` | Node.js, Bun, Next.js, Workers | 2 |\n| Python | `cloudflare` | FastAPI, Django, scripts | 2 |\n| Go | `cloudflare-go/v4` | CLI tools, microservices | 10 |\n\nAll SDKs are Stainless-generated from OpenAPI spec (consistent APIs).\n\n## Authentication Methods\n\n| Method | Security | Use Case | Scope |\n|--------|----------|----------|-------|\n| **API Token** ✓ | Scoped, rotatable | Production | Per-zone or account |\n| API Key + Email | Full account access | Legacy only | Everything |\n| User Service Key | Limited | Origin CA certs only | Origin CA |\n\n**Always use API tokens** for new projects.\n\n## Rate Limits\n\n| Limit | Value |\n|-------|-------|\n| Per user/token | 1200 requests / 5 minutes |\n| Per IP | 200 requests / second |\n| GraphQL | 320 / 5 minutes (cost-based) |\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| Initialize SDK client | api.md |\n| Configure auth/timeout/retry | configuration.md |\n| Find usage patterns | patterns.md |\n| Debug errors/rate limits | gotchas.md |\n| Product-specific APIs | ../workers/, ../r2/, ../kv/, etc. |\n\n## In This Reference\n\n- **[api.md](api.md)** - SDK client initialization, pagination, error handling, examples\n- **[configuration.md](configuration.md)** - Environment variables, SDK config, Wrangler setup\n- **[patterns.md](patterns.md)** - Real-world patterns, batch operations, workflows\n- **[gotchas.md](gotchas.md)** - Rate limits, SDK-specific issues, troubleshooting\n\n## See Also\n\n- [Cloudflare API Docs](https://developers.cloudflare.com/api/)\n- [Bindings Reference](../bindings/) - Workers runtime bindings (preferred over REST API)\n- [Wrangler Reference](../wrangler/) - CLI tool for Cloudflare development\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api/api.md", "content": "# API Reference\n\n## Client Initialization\n\n### TypeScript\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN,\n});\n```\n\n### Python\n\n```python\nfrom cloudflare import Cloudflare\n\nclient = Cloudflare(api_token=os.environ.get(\"CLOUDFLARE_API_TOKEN\"))\n\n# For async:\nfrom cloudflare import AsyncCloudflare\nclient = AsyncCloudflare(api_token=os.environ[\"CLOUDFLARE_API_TOKEN\"])\n```\n\n### Go\n\n```go\nimport (\n \"github.com/cloudflare/cloudflare-go/v4\"\n \"github.com/cloudflare/cloudflare-go/v4/option\"\n)\n\nclient := cloudflare.NewClient(\n option.WithAPIToken(os.Getenv(\"CLOUDFLARE_API_TOKEN\")),\n)\n```\n\n## Authentication\n\n### API Token (Recommended)\n\n**Create token**: Dashboard → My Profile → API Tokens → Create Token\n\n```bash\nexport CLOUDFLARE_API_TOKEN='your-token-here'\n\ncurl \"https://api.cloudflare.com/client/v4/zones\" \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\"\n```\n\n**Token scopes**: Always use minimal permissions (zone-specific, time-limited).\n\n### API Key (Legacy)\n\n```bash\ncurl \"https://api.cloudflare.com/client/v4/zones\" \\\n --header \"X-Auth-Email: user@example.com\" \\\n --header \"X-Auth-Key: $CLOUDFLARE_API_KEY\"\n```\n\n**Not recommended:** Full account access, cannot scope permissions.\n\n## Auto-Pagination\n\nAll SDKs support automatic pagination for list operations.\n\n```typescript\n// TypeScript: for await...of\nfor await (const zone of client.zones.list()) {\n console.log(zone.id);\n}\n```\n\n```python\n# Python: iterator protocol\nfor zone in client.zones.list():\n print(zone.id)\n```\n\n```go\n// Go: ListAutoPaging\niter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})\nfor iter.Next() {\n zone := iter.Current()\n fmt.Println(zone.ID)\n}\n```\n\n## Error Handling\n\n```typescript\ntry {\n const zone = await client.zones.get({ zone_id: 'xxx' });\n} catch (err) {\n if (err instanceof Cloudflare.NotFoundError) {\n // 404\n } else if (err instanceof Cloudflare.RateLimitError) {\n // 429 - SDK auto-retries with backoff\n } else if (err instanceof Cloudflare.APIError) {\n console.log(err.status, err.message);\n }\n}\n```\n\n**Common Error Types:**\n- `AuthenticationError` (401) - Invalid token\n- `PermissionDeniedError` (403) - Insufficient scope\n- `NotFoundError` (404) - Resource not found\n- `RateLimitError` (429) - Rate limit exceeded\n- `InternalServerError` (≥500) - Cloudflare error\n\n## Zone Management\n\n```typescript\n// List zones\nconst zones = await client.zones.list({\n account: { id: 'account-id' },\n status: 'active',\n});\n\n// Create zone\nconst zone = await client.zones.create({\n account: { id: 'account-id' },\n name: 'example.com',\n type: 'full', // or 'partial'\n});\n\n// Update zone\nawait client.zones.edit('zone-id', {\n paused: false,\n});\n\n// Delete zone\nawait client.zones.delete('zone-id');\n```\n\n```go\n// Go: requires cloudflare.F() wrapper\nzone, err := client.Zones.New(ctx, cloudflare.ZoneNewParams{\n Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{\n ID: cloudflare.F(\"account-id\"),\n }),\n Name: cloudflare.F(\"example.com\"),\n Type: cloudflare.F(cloudflare.ZoneNewParamsTypeFull),\n})\n```\n\n## DNS Management\n\n```typescript\n// Create DNS record\nawait client.dns.records.create({\n zone_id: 'zone-id',\n type: 'A',\n name: 'subdomain.example.com',\n content: '192.0.2.1',\n ttl: 1, // auto\n proxied: true, // Orange cloud\n});\n\n// List DNS records (with auto-pagination)\nfor await (const record of client.dns.records.list({\n zone_id: 'zone-id',\n type: 'A',\n})) {\n console.log(record.name, record.content);\n}\n\n// Update DNS record\nawait client.dns.records.update({\n zone_id: 'zone-id',\n dns_record_id: 'record-id',\n type: 'A',\n name: 'subdomain.example.com',\n content: '203.0.113.1',\n proxied: true,\n});\n\n// Delete DNS record\nawait client.dns.records.delete({\n zone_id: 'zone-id',\n dns_record_id: 'record-id',\n});\n```\n\n```python\n# Python example\nclient.dns.records.create(\n zone_id=\"zone-id\",\n type=\"A\",\n name=\"subdomain.example.com\",\n content=\"192.0.2.1\",\n ttl=1,\n proxied=True,\n)\n```\n\n## See Also\n\n- [configuration.md](./configuration.md) - SDK configuration, environment variables\n- [patterns.md](./patterns.md) - Real-world patterns and workflows\n- [gotchas.md](./gotchas.md) - Rate limits, troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api/configuration.md", "content": "# Configuration\n\n## Environment Variables\n\n### Set Variables\n\n| Platform | Command |\n|----------|---------|\n| Linux/macOS | `export CLOUDFLARE_API_TOKEN='token'` |\n| PowerShell | `$env:CLOUDFLARE_API_TOKEN = 'token'` |\n| Windows CMD | `set CLOUDFLARE_API_TOKEN=token` |\n\n**Security:** Never commit tokens. Use `.env` files (gitignored) or secret managers.\n\n### .env File Pattern\n\n```bash\n# .env (add to .gitignore)\nCLOUDFLARE_API_TOKEN=your-token-here\nCLOUDFLARE_ACCOUNT_ID=your-account-id\n```\n\n```typescript\n// TypeScript\nimport 'dotenv/config';\n\nconst client = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN,\n});\n```\n\n```python\n# Python\nfrom dotenv import load_dotenv\nload_dotenv()\n\nclient = Cloudflare(api_token=os.environ[\"CLOUDFLARE_API_TOKEN\"])\n```\n\n## SDK Configuration\n\n### TypeScript\n\n```typescript\nconst client = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN,\n timeout: 120000, // 2 min (default 60s), in milliseconds\n maxRetries: 5, // default 2\n baseURL: 'https://...', // proxy (rare)\n});\n\n// Per-request overrides\nawait client.zones.get(\n { zone_id: 'zone-id' },\n { timeout: 5000, maxRetries: 0 }\n);\n```\n\n### Python\n\n```python\nclient = Cloudflare(\n api_token=os.environ[\"CLOUDFLARE_API_TOKEN\"],\n timeout=120, # seconds (default 60)\n max_retries=5, # default 2\n base_url=\"https://...\", # proxy (rare)\n)\n\n# Per-request overrides\nclient.with_options(timeout=5, max_retries=0).zones.get(zone_id=\"zone-id\")\n```\n\n### Go\n\n```go\nclient := cloudflare.NewClient(\n option.WithAPIToken(os.Getenv(\"CLOUDFLARE_API_TOKEN\")),\n option.WithMaxRetries(5), // default 10 (higher than TS/Python)\n option.WithRequestTimeout(2 * time.Minute), // default 60s\n option.WithBaseURL(\"https://...\"), // proxy (rare)\n)\n\n// Per-request overrides\nclient.Zones.Get(ctx, \"zone-id\", option.WithMaxRetries(0))\n```\n\n## Configuration Options\n\n| Option | TypeScript | Python | Go | Default |\n|--------|-----------|--------|-----|---------|\n| Timeout | `timeout` (ms) | `timeout` (s) | `WithRequestTimeout` | 60s |\n| Retries | `maxRetries` | `max_retries` | `WithMaxRetries` | 2 (Go: 10) |\n| Base URL | `baseURL` | `base_url` | `WithBaseURL` | api.cloudflare.com |\n\n**Note:** Go SDK has higher default retries (10) than TypeScript/Python (2).\n\n## Timeout Configuration\n\n**When to increase:**\n- Large zone transfers\n- Bulk DNS operations\n- Worker script uploads\n\n```typescript\nconst client = new Cloudflare({\n timeout: 300000, // 5 minutes\n});\n```\n\n## Retry Configuration\n\n**When to increase:** Rate-limit-heavy workflows, flaky network\n\n**When to decrease:** Fast-fail requirements, user-facing requests\n\n```typescript\n// Increase retries for batch operations\nconst client = new Cloudflare({ maxRetries: 10 });\n\n// Disable retries for fast-fail\nconst fastClient = new Cloudflare({ maxRetries: 0 });\n```\n\n## Wrangler CLI Integration\n\n```bash\n# Configure authentication\nwrangler login\n# Or\nexport CLOUDFLARE_API_TOKEN='token'\n\n# Common commands that use API\nwrangler deploy # Uploads worker via API\nwrangler kv:key put # KV operations\nwrangler r2 bucket create # R2 operations\nwrangler d1 execute # D1 operations\nwrangler pages deploy # Pages operations\n\n# Get API configuration\nwrangler whoami # Shows authenticated user\n```\n\n### wrangler.toml\n\n```toml\nname = \"my-worker\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2024-01-01\"\naccount_id = \"your-account-id\"\n\n# Can also use env vars:\n# CLOUDFLARE_ACCOUNT_ID\n# CLOUDFLARE_API_TOKEN\n```\n\n## See Also\n\n- [api.md](./api.md) - Client initialization, authentication\n- [gotchas.md](./gotchas.md) - Rate limits, timeout errors\n- [Wrangler Reference](../wrangler/) - CLI tool details\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Rate Limits & 429 Errors\n\n**Actual Limits:**\n- **1200 requests / 5 minutes** per user/token (global)\n- **200 requests / second** per IP address\n- **GraphQL: 320 / 5 minutes** (cost-based)\n\n**SDK Behavior:**\n- Auto-retry with exponential backoff (default 2 retries, Go: 10)\n- Respects `Retry-After` header\n- Throws `RateLimitError` after exhausting retries\n\n**Solution:**\n\n```typescript\n// Increase retries for rate-limit-heavy workflows\nconst client = new Cloudflare({ maxRetries: 5 });\n\n// Add application-level throttling\nimport pLimit from 'p-limit';\nconst limit = pLimit(10); // Max 10 concurrent requests\n```\n\n## SDK-Specific Issues\n\n### Go: Required Field Wrapper\n\n**Problem:** Go SDK requires `cloudflare.F()` wrapper for optional fields.\n\n```go\n// ❌ WRONG - Won't compile or send field\nclient.Zones.New(ctx, cloudflare.ZoneNewParams{\n Name: \"example.com\",\n})\n\n// ✅ CORRECT\nclient.Zones.New(ctx, cloudflare.ZoneNewParams{\n Name: cloudflare.F(\"example.com\"),\n Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{\n ID: cloudflare.F(\"account-id\"),\n }),\n})\n```\n\n**Why:** Distinguishes between zero value, null, and omitted fields.\n\n### Python: Async vs Sync Clients\n\n**Problem:** Using sync client in async context or vice versa.\n\n```python\n# ❌ WRONG - Can't await sync client\nfrom cloudflare import Cloudflare\nclient = Cloudflare()\nawait client.zones.list() # TypeError\n\n# ✅ CORRECT - Use AsyncCloudflare\nfrom cloudflare import AsyncCloudflare\nclient = AsyncCloudflare()\nawait client.zones.list()\n```\n\n## Token Permission Errors (403)\n\n**Problem:** API returns 403 Forbidden despite valid token.\n\n**Cause:** Token lacks required permissions (scope).\n\n**Scopes Required:**\n\n| Operation | Required Scope |\n|-----------|----------------|\n| List zones | Zone:Read (zone-level or account-level) |\n| Create zone | Zone:Edit (account-level) |\n| Edit DNS | DNS:Edit (zone-level) |\n| Deploy Worker | Workers Script:Edit (account-level) |\n| Read KV | Workers KV Storage:Read |\n| Write KV | Workers KV Storage:Edit |\n\n**Solution:** Re-create token with correct permissions in Dashboard → My Profile → API Tokens.\n\n## Pagination Truncation\n\n**Problem:** Only getting first 20 results (default page size).\n\n**Solution:** Use auto-pagination iterators.\n\n```typescript\n// ❌ WRONG - Only first page (20 items)\nconst page = await client.zones.list();\n\n// ✅ CORRECT - All results\nconst zones = [];\nfor await (const zone of client.zones.list()) {\n zones.push(zone);\n}\n```\n\n## Workers Subrequests\n\n**Problem:** Rate limit hit faster than expected in Workers.\n\n**Cause:** Workers subrequests count as separate API calls.\n\n**Solution:** Use bindings instead of REST API in Workers (see ../bindings/).\n\n```typescript\n// ❌ WRONG - REST API in Workers (counts against rate limit)\nconst client = new Cloudflare({ apiToken: env.CLOUDFLARE_API_TOKEN });\nconst zones = await client.zones.list();\n\n// ✅ CORRECT - Use bindings (no rate limit)\n// Access via env.MY_BINDING\n```\n\n## Authentication Errors (401)\n\n**Problem:** \"Authentication failed\" or \"Invalid token\"\n\n**Causes:**\n- Token expired\n- Token deleted/revoked\n- Token not set in environment\n- Wrong token format\n\n**Solution:**\n\n```typescript\n// Verify token is set\nif (!process.env.CLOUDFLARE_API_TOKEN) {\n throw new Error('CLOUDFLARE_API_TOKEN not set');\n}\n\n// Test token\nconst user = await client.user.tokens.verify();\nconsole.log('Token valid:', user.status);\n```\n\n## Timeout Errors\n\n**Problem:** Request times out (default 60s).\n\n**Cause:** Large operations (bulk DNS, zone transfers).\n\n**Solution:** Increase timeout or split operations.\n\n```typescript\n// Increase timeout\nconst client = new Cloudflare({\n timeout: 300000, // 5 minutes\n});\n\n// Or split operations\nconst batchSize = 100;\nfor (let i = 0; i < records.length; i += batchSize) {\n const batch = records.slice(i, i + batchSize);\n await processBatch(batch);\n}\n```\n\n## Zone Not Found (404)\n\n**Problem:** Zone ID valid but returns 404.\n\n**Causes:**\n- Zone not in account associated with token\n- Zone deleted\n- Wrong zone ID format\n\n**Solution:**\n\n```typescript\n// List all zones to find correct ID\nfor await (const zone of client.zones.list()) {\n console.log(zone.id, zone.name);\n}\n```\n\n## Limits Reference\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| API rate limit | 1200/5min | Per user/token |\n| IP rate limit | 200/sec | Per IP |\n| GraphQL rate limit | 320/5min | Cost-based |\n| Parallel requests (recommended) | < 10 | Avoid overwhelming API |\n| Default page size | 20 | Use auto-pagination |\n| Max page size | 50 | Some endpoints |\n\n## Best Practices\n\n**Security:**\n- Never commit tokens\n- Use minimal permissions\n- Rotate tokens regularly\n- Set token expiration\n\n**Performance:**\n- Batch operations\n- Use pagination wisely\n- Cache responses\n- Handle rate limits\n\n**Code Organization:**\n\n```typescript\n// Create reusable client instance\nexport const cfClient = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN,\n maxRetries: 5,\n});\n\n// Wrap common operations\nexport async function getZoneDetails(zoneId: string) {\n return await cfClient.zones.get({ zone_id: zoneId });\n}\n```\n\n## See Also\n\n- [api.md](./api.md) - Error types, authentication\n- [configuration.md](./configuration.md) - Timeout/retry configuration\n- [patterns.md](./patterns.md) - Error handling patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api/patterns.md", "content": "# Common Patterns\n\n## List All with Auto-Pagination\n\n**Problem:** API returns paginated results. Default page size is 20.\n\n**Solution:** Use SDK auto-pagination to iterate all results.\n\n```typescript\n// TypeScript\nfor await (const zone of client.zones.list()) {\n console.log(zone.name);\n}\n```\n\n```python\n# Python\nfor zone in client.zones.list():\n print(zone.name)\n```\n\n```go\n// Go\niter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})\nfor iter.Next() {\n fmt.Println(iter.Current().Name)\n}\n```\n\n## Error Handling with Retry\n\n**Problem:** Rate limits (429) and transient errors need retry.\n\n**Solution:** SDKs auto-retry with exponential backoff. Customize as needed.\n\n```typescript\n// Increase retries for rate-limit-heavy operations\nconst client = new Cloudflare({ maxRetries: 5 });\n\ntry {\n const zone = await client.zones.create({ /* ... */ });\n} catch (err) {\n if (err instanceof Cloudflare.RateLimitError) {\n // Already retried 5 times with backoff\n const retryAfter = err.headers['retry-after'];\n console.log(`Rate limited. Retry after ${retryAfter}s`);\n }\n}\n```\n\n## Batch Parallel Operations\n\n**Problem:** Need to create multiple resources quickly.\n\n**Solution:** Use `Promise.all()` for parallel requests (respect rate limits).\n\n```typescript\n// Create multiple DNS records in parallel\nconst records = ['www', 'api', 'cdn'].map(subdomain =>\n client.dns.records.create({\n zone_id: 'zone-id',\n type: 'A',\n name: `${subdomain}.example.com`,\n content: '192.0.2.1',\n })\n);\nawait Promise.all(records);\n```\n\n**Controlled concurrency** (avoid rate limits):\n\n```typescript\nimport pLimit from 'p-limit';\nconst limit = pLimit(10); // Max 10 concurrent\n\nconst subdomains = ['www', 'api', 'cdn', /* many more */];\nconst records = subdomains.map(subdomain =>\n limit(() => client.dns.records.create({\n zone_id: 'zone-id',\n type: 'A',\n name: `${subdomain}.example.com`,\n content: '192.0.2.1',\n }))\n);\nawait Promise.all(records);\n```\n\n## Zone CRUD Workflow\n\n```typescript\n// Create\nconst zone = await client.zones.create({\n account: { id: 'account-id' },\n name: 'example.com',\n type: 'full',\n});\n\n// Read\nconst fetched = await client.zones.get({ zone_id: zone.id });\n\n// Update\nawait client.zones.edit(zone.id, { paused: false });\n\n// Delete\nawait client.zones.delete(zone.id);\n```\n\n## DNS Bulk Update\n\n```typescript\n// Fetch all A records\nconst records = [];\nfor await (const record of client.dns.records.list({\n zone_id: 'zone-id',\n type: 'A',\n})) {\n records.push(record);\n}\n\n// Update all to new IP\nawait Promise.all(records.map(record =>\n client.dns.records.update({\n zone_id: 'zone-id',\n dns_record_id: record.id,\n type: 'A',\n name: record.name,\n content: '203.0.113.1', // New IP\n proxied: record.proxied,\n ttl: record.ttl,\n })\n));\n```\n\n## Filter and Collect Results\n\n```typescript\n// Find all proxied A records\nconst proxiedRecords = [];\nfor await (const record of client.dns.records.list({\n zone_id: 'zone-id',\n type: 'A',\n})) {\n if (record.proxied) {\n proxiedRecords.push(record);\n }\n}\n```\n\n## Error Recovery Pattern\n\n```typescript\nasync function createZoneWithRetry(name: string, maxAttempts = 3) {\n for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n try {\n return await client.zones.create({\n account: { id: 'account-id' },\n name,\n type: 'full',\n });\n } catch (err) {\n if (err instanceof Cloudflare.RateLimitError && attempt < maxAttempts) {\n const retryAfter = parseInt(err.headers['retry-after'] || '5');\n console.log(`Rate limited, waiting ${retryAfter}s (retry ${attempt}/${maxAttempts})`);\n await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));\n } else {\n throw err;\n }\n }\n }\n}\n```\n\n## Conditional Update Pattern\n\n```typescript\n// Only update if zone is active\nconst zone = await client.zones.get({ zone_id: 'zone-id' });\nif (zone.status === 'active') {\n await client.zones.edit(zone.id, { paused: false });\n}\n```\n\n## Batch with Error Handling\n\n```typescript\n// Process multiple zones, continue on errors\nconst results = await Promise.allSettled(\n zoneIds.map(id => client.zones.get({ zone_id: id }))\n);\n\nresults.forEach((result, i) => {\n if (result.status === 'fulfilled') {\n console.log(`Zone ${i}: ${result.value.name}`);\n } else {\n console.error(`Zone ${i} failed:`, result.reason.message);\n }\n});\n```\n\n## See Also\n\n- [api.md](./api.md) - SDK client initialization, basic operations\n- [gotchas.md](./gotchas.md) - Rate limits, common errors\n- [configuration.md](./configuration.md) - SDK configuration options\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api-shield/README.md", "content": "# Cloudflare API Shield Reference\n\nExpert guidance for API Shield - comprehensive API security suite for discovery, protection, and monitoring.\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| Initial setup | README → configuration.md |\n| Implement JWT validation | configuration.md → api.md |\n| Add schema validation | configuration.md → patterns.md |\n| Detect API attacks | patterns.md → api.md |\n| Debug issues | gotchas.md |\n\n## Feature Selection\n\nWhat protection do you need?\n\n```\n├─ Validate request/response structure → Schema Validation 2.0 (configuration.md)\n├─ Verify auth tokens → JWT Validation (configuration.md)\n├─ Client certificates → mTLS (configuration.md)\n├─ Detect BOLA attacks → BOLA Detection (patterns.md)\n├─ Track auth coverage → Auth Posture (patterns.md)\n├─ Stop volumetric abuse → Abuse Detection (patterns.md)\n└─ Discover shadow APIs → API Discovery (api.md)\n```\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, session identifiers, rules, token/mTLS configs\n- **[api.md](api.md)** - Endpoint management, discovery, validation APIs, GraphQL operations\n- **[patterns.md](patterns.md)** - Common patterns, progressive rollout, OWASP mappings, workflows\n- **[gotchas.md](gotchas.md)** - Troubleshooting, false positives, performance, best practices\n\n## Quick Start\n\nAPI Shield: Enterprise-grade API security (Discovery, Schema Validation 2.0, JWT, mTLS, BOLA Detection, Auth Posture). Available as Enterprise add-on with preview access.\n\n## See Also\n\n- [API Shield Docs](https://developers.cloudflare.com/api-shield/)\n- [API Reference](https://developers.cloudflare.com/api/resources/api_gateway/)\n- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api-shield/api.md", "content": "# API Reference\n\nBase: `/zones/{zone_id}/api_gateway`\n\n## Endpoints\n\n```bash\nGET /operations # List\nGET /operations/{op_id} # Get single\nPOST /operations/item # Create: {endpoint,host,method}\nPOST /operations # Bulk: {operations:[{endpoint,host,method}]}\nDELETE /operations/{op_id} # Delete\nDELETE /operations # Bulk delete: {operation_ids:[...]}\n```\n\n## Discovery\n\n```bash\nGET /discovery/operations # List discovered\nPATCH /discovery/operations/{op_id} # Update: {state:\"saved\"|\"ignored\"}\nPATCH /discovery/operations # Bulk: {operation_ids:{id:{state}}}\nGET /discovery # OpenAPI export\n```\n\n## Config\n\n```bash\nGET /configuration # Get session ID config\nPUT /configuration # Update: {auth_id_characteristics:[{name,type:\"header\"|\"cookie\"}]}\n```\n\n## Token Validation\n\n```bash\nGET /token_validation # List\nPOST /token_validation # Create: {name,location:{header:\"...\"},jwks:\"...\"}\nPOST /jwt_validation_rules # Rule: {name,hostname,token_validation_id,action:\"block\"}\n```\n\n## Workers Integration\n\n### Access JWT Claims\n```js\nexport default {\n async fetch(req, env) {\n // Access validated JWT payload\n const jwt = req.cf?.jwt?.payload?.[env.JWT_CONFIG_ID]?.[0];\n if (jwt) {\n const userId = jwt.sub;\n const role = jwt.role;\n }\n }\n}\n```\n\n### Access mTLS Info\n```js\nexport default {\n async fetch(req, env) {\n const tls = req.cf?.tlsClientAuth;\n if (tls?.certVerified === 'SUCCESS') {\n const fingerprint = tls.certFingerprintSHA256;\n // Authenticated client\n }\n }\n}\n```\n\n### Dynamic JWKS Update\n```js\nexport default {\n async scheduled(event, env) {\n const jwks = await (await fetch('https://auth.example.com/.well-known/jwks.json')).json();\n await fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/api_gateway/token_validation/${env.CONFIG_ID}`, {\n method: 'PATCH',\n headers: {'Authorization': `Bearer ${env.CF_API_TOKEN}`, 'Content-Type': 'application/json'},\n body: JSON.stringify({jwks: JSON.stringify(jwks)})\n });\n }\n}\n```\n\n## Firewall Fields\n\n### Core Fields\n```js\ncf.api_gateway.auth_id_present // Session ID present\ncf.api_gateway.request_violates_schema // Schema violation\ncf.api_gateway.fallthrough_triggered // No endpoint match\ncf.tls_client_auth.cert_verified // mTLS cert valid\ncf.tls_client_auth.cert_fingerprint_sha256\n```\n\n### JWT Validation (2026)\n```js\n// Modern validation syntax\nis_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0])\n\n// Legacy (still supported)\ncf.api_gateway.jwt_claims_valid\n\n// Extract claims\nlookup_json_string(http.request.jwt.payload[\"{config_id}\"][0], \"claim_name\")\n```\n\n### Risk Labels (2026)\n```js\n// BOLA detection\ncf.api_gateway.cf-risk-bola-enumeration // Sequential resource access detected\ncf.api_gateway.cf-risk-bola-pollution // Parameter pollution detected\n\n// Authentication posture\ncf.api_gateway.cf-risk-missing-auth // Endpoint lacks authentication\ncf.api_gateway.cf-risk-mixed-auth // Inconsistent auth patterns\n```\n\n## BOLA Detection\n\n```bash\nGET /user_schemas/{schema_id}/bola # Get BOLA config\nPATCH /user_schemas/{schema_id}/bola # Update: {enabled:true}\n```\n\n## Auth Posture\n\n```bash\nGET /discovery/authentication_posture # List unprotected endpoints\n```\n\n## GraphQL Protection\n\n```bash\nGET /settings/graphql_protection # Get limits\nPUT /settings/graphql_protection # Set: {max_depth,max_size}\n```\n\n## See Also\n\n- [configuration.md](configuration.md) - Setup guides for all features\n- [patterns.md](patterns.md) - Firewall rules and common patterns\n- [API Gateway API Docs](https://developers.cloudflare.com/api/resources/api_gateway/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api-shield/configuration.md", "content": "# Configuration\n\n## Schema Validation 2.0 Setup\n\n> ⚠️ **Classic Schema Validation deprecated.** Use Schema Validation 2.0.\n\n**Upload schema (Dashboard):**\n```\nSecurity > API Shield > Schema Validation > Add validation\n- Upload .yml/.yaml/.json (OpenAPI v3.0)\n- Endpoints auto-added to Endpoint Management\n- Action: Log | Block | None\n- Body inspection: JSON payloads\n```\n\n**Change validation action:**\n```\nSecurity > API Shield > Settings > Schema Validation\nPer-endpoint: Filter → ellipses → Change action\nDefault action: Set global mitigation action\n```\n\n**Migration from Classic:**\n```\n1. Export existing schema (if available)\n2. Delete all Classic schema validation rules\n3. Wait 5 min for cache clear\n4. Re-upload via Schema Validation 2.0 interface\n5. Verify in Security > Events\n```\n\n**Fallthrough rule** (catch-all unknown endpoints):\n```\nSecurity > API Shield > Settings > Fallthrough > Use Template\n- Select hostnames\n- Create rule with cf.api_gateway.fallthrough_triggered\n- Action: Log (discover) or Block (strict)\n```\n\n**Body inspection:** Supports `application/json`, `*/*`, `application/*`. Disable origin MIME sniffing to prevent bypasses.\n\n## JWT Validation\n\n**Setup token config:**\n```\nSecurity > API Shield > Settings > JWT Settings > Add configuration\n- Name: \"Auth0 JWT Config\"\n- Location: Header/Cookie + name (e.g., \"Authorization\")\n- JWKS: Paste public keys from IdP\n```\n\n**Create validation rule:**\n```\nSecurity > API Shield > API Rules > Add rule\n- Hostname: api.example.com\n- Deselect endpoints to ignore\n- Token config: Select config\n- Enforce presence: Ignore or Mark as non-compliant\n- Action: Log/Block/Challenge\n```\n\n**Rate limit by JWT claim:**\n```wirefilter\nlookup_json_string(http.request.jwt.claims[\"{config_id}\"][0], \"sub\")\n```\n\n**Special cases:**\n- Two JWTs, different IdPs: Create 2 configs, select both, \"Validate all\"\n- IdP migration: 2 configs + 2 rules, adjust actions per state\n- Bearer prefix: API Shield handles with/without\n- Nested claims: Dot notation `user.email`\n\n## Mutual TLS (mTLS)\n\n**Setup:**\n```\nSSL/TLS > Client Certificates > Create Certificate\n- Generate CF-managed CA (all plans)\n- Upload custom CA (Enterprise, max 5)\n```\n\n**Configure mTLS rule:**\n```\nSecurity > API Shield > mTLS\n- Select hostname(s)\n- Choose certificate(s)\n- Action: Block/Log/Challenge\n```\n\n**Test:**\n```bash\nopenssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365\ncurl https://api.example.com/endpoint --cert client-cert.pem --key client-key.pem\n```\n\n## Session Identifiers\n\nCritical for BOLA Detection, Sequence Mitigation, and analytics. Configure header/cookie that uniquely IDs API users.\n\n**Examples:** JWT sub claim, session token, API key, custom user ID header\n\n**Configure:**\n```\nSecurity > API Shield > Settings > Session Identifiers\n- Type: Header/Cookie\n- Name: \"X-User-ID\" or \"Authorization\"\n```\n\n## BOLA Detection\n\nDetects Broken Object Level Authorization attacks (enumeration + parameter pollution).\n\n**Enable:**\n```\nSecurity > API Shield > Schema Validation > [Select Schema] > BOLA Detection\n- Enable detection\n- Threshold: Sensitivity level (Low/Medium/High)\n- Action: Log or Block\n```\n\n**Requirements:**\n- Schema Validation 2.0 enabled\n- Session identifiers configured\n- Minimum traffic: 1000+ requests/day per endpoint\n\n## Authentication Posture\n\nIdentifies unprotected or inconsistently protected endpoints.\n\n**View report:**\n```\nSecurity > API Shield > Authentication Posture\n- Shows endpoints lacking JWT/mTLS\n- Highlights mixed authentication patterns\n```\n\n**Remediate:**\n1. Review flagged endpoints\n2. Add JWT validation rules\n3. Configure mTLS for sensitive endpoints\n4. Monitor posture score\n\n## Volumetric Abuse + GraphQL\n\n**Volumetric Abuse Detection:**\n`Security > API Shield > Settings > Volumetric Abuse Detection`\n- Enable per-endpoint monitoring, set thresholds, action: Log | Challenge | Block\n\n**GraphQL Protection:**\n`Security > API Shield > Settings > GraphQL Protection`\n- Max query depth: 10, max size: 100KB, block introspection (production)\n\n## Terraform\n\n```hcl\n# Session identifier\nresource \"cloudflare_api_shield\" \"main\" {\n zone_id = var.zone_id\n auth_id_characteristics {\n type = \"header\"\n name = \"Authorization\"\n }\n}\n\n# Add endpoint\nresource \"cloudflare_api_shield_operation\" \"users_get\" {\n zone_id = var.zone_id\n method = \"GET\"\n host = \"api.example.com\"\n endpoint = \"/api/users/{id}\"\n}\n\n# JWT validation rule\nresource \"cloudflare_ruleset\" \"jwt_validation\" {\n zone_id = var.zone_id\n name = \"API JWT Validation\"\n kind = \"zone\"\n phase = \"http_request_firewall_custom\"\n\n rules {\n action = \"block\"\n expression = \"(http.host eq \\\"api.example.com\\\" and not is_jwt_valid(http.request.jwt.payload[\\\"{config_id}\\\"][0]))\"\n description = \"Block invalid JWTs\"\n }\n}\n```\n\n## See Also\n\n- [api.md](api.md) - API endpoints and Workers integration\n- [patterns.md](patterns.md) - Firewall rules and deployment patterns\n- [gotchas.md](gotchas.md) - Troubleshooting and limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api-shield/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"Schema Validation 2.0 not working after migration\"\n\n**Cause:** Classic rules still active, conflicting with new system\n**Solution:**\n1. Delete ALL Classic schema validation rules\n2. Clear Cloudflare cache (wait 5 min)\n3. Re-upload schema via new Schema Validation 2.0 interface\n4. Verify in Security > Events\n5. Check action is set (Log/Block)\n\n### \"Schema validation blocking valid requests\"\n\n**Cause:** Schema too restrictive, missing fields, or incorrect types\n**Solution:** \n1. Check Firewall Events for violation details\n2. Review schema in Settings\n3. Test schema in Swagger Editor\n4. Use Log mode to validate before blocking\n5. Update schema with correct specifications\n6. Ensure Schema Validation 2.0 (not Classic)\n\n### \"JWT validation failing\"\n\n**Cause:** JWKS mismatch with IdP, expired token, wrong header/cookie name, or clock skew\n**Solution:** \n1. Verify JWKS matches IdP configuration\n2. Check token `exp` claim is valid\n3. Confirm header/cookie name matches config\n4. Test token at jwt.io\n5. Account for clock skew (±5 min tolerance)\n6. Use modern syntax: `is_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0])`\n\n### \"BOLA detection false positives\"\n\n**Cause:** Legitimate sequential access patterns, bulk operations, or sensitivity too high\n**Solution:**\n1. Review BOLA events in Security > Events\n2. Lower sensitivity threshold (High → Medium → Low)\n3. Exclude legitimate bulk operations from detection\n4. Ensure session identifiers uniquely identify users\n5. Verify minimum traffic requirements met (1000+ req/day)\n\n### \"Risk labels not appearing in firewall rules\"\n\n**Cause:** Feature not enabled, insufficient traffic, or missing session identifiers\n**Solution:**\n1. Verify Schema Validation 2.0 enabled\n2. Enable BOLA Detection in schema settings\n3. Configure session identifiers (required for BOLA)\n4. Wait 24-48h for ML model training\n5. Check minimum traffic thresholds met\n\n### \"Endpoint discovery not finding APIs\"\n\n**Cause:** Insufficient traffic (<500 reqs/10d), non-2xx responses, Worker direct requests, or incorrect session ID config\n**Solution:** Ensure 500+ requests in 10 days, 2xx responses from edge (not Workers direct), configure session IDs correctly. ML updates daily.\n\n### \"Sequence detection false positives\"\n\n**Cause:** Lookback window issues, non-unique session IDs, or model sensitivity\n**Solution:** \n1. Review lookback settings (10 reqs to managed endpoints, 10min window)\n2. Ensure session ID uniqueness per user (not shared tokens)\n3. Adjust positive/negative model balance\n4. Exclude legitimate workflows from detection\n\n### \"GraphQL protection blocking valid queries\"\n\n**Cause:** Query depth/size limits too restrictive, complex but legitimate queries\n**Solution:**\n1. Review blocked query patterns in Security > Events\n2. Increase max_depth (default: 10) if needed\n3. Increase max_size (default: 100KB) for complex queries\n4. Whitelist specific query signatures\n5. Use Log mode to tune before blocking\n\n### \"Token invalid\"\n\n**Cause:** Configuration error, JWKS mismatch, or expired token\n**Solution:** Verify config matches IdP, update JWKS, check token expiration\n\n### \"Schema violation\"\n\n**Cause:** Missing required fields, wrong data types, or spec mismatch\n**Solution:** Review schema against actual requests, ensure all required fields present, validate types match spec\n\n### \"Fallthrough\"\n\n**Cause:** Unknown endpoint or pattern mismatch\n**Solution:** Update schema with all endpoints, check path pattern matching\n\n### \"mTLS failed\"\n\n**Cause:** Certificate untrusted/expired or wrong CA\n**Solution:** Verify cert chain, check expiration, confirm correct CA uploaded\n\n## Limits (2026)\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| OpenAPI version | v3.0.x only | No external refs, must be valid |\n| Schema operations | 10K (Enterprise) | Contact for higher limits |\n| JWT validation sources | Headers/cookies only | No query params/body |\n| Endpoint discovery | 500+ reqs/10d | Minimum for ML model |\n| Path normalization | Automatic | `/profile/238` → `/profile/{var1}` |\n| Schema parameters | No `content` field | No object param validation |\n| BOLA detection | 1000+ reqs/day/endpoint | Per-endpoint minimum |\n| Session ID uniqueness | Required | BOLA/Sequence need unique IDs |\n| GraphQL max depth | 1-50 | Default: 10 |\n| GraphQL max size | 1KB-1MB | Default: 100KB |\n| JWT claim nesting | 10 levels max | Use dot notation |\n| mTLS CA certificates | 5 custom max | CF-managed unlimited |\n| Schema upload size | 5MB max | Compressed OpenAPI spec |\n| Volumetric abuse baseline | 7 days training | Initial ML period |\n| Auth Posture refresh | Daily | Updated nightly |\n\n## See Also\n\n- [configuration.md](configuration.md) - Setup guides to avoid common issues\n- [patterns.md](patterns.md) - Best practices and progressive rollout\n- [API Shield Docs](https://developers.cloudflare.com/api-shield/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/api-shield/patterns.md", "content": "# Patterns & Use Cases\n\n## Protect API with Schema + JWT\n\n```bash\n# 1. Upload OpenAPI schema\nPOST /zones/{zone_id}/api_gateway/user_schemas\n\n# 2. Configure JWT validation\nPOST /zones/{zone_id}/api_gateway/token_validation\n{\n \"name\": \"Auth0\",\n \"location\": {\"header\": \"Authorization\"},\n \"jwks\": \"{...}\"\n}\n\n# 3. Create JWT rule\nPOST /zones/{zone_id}/api_gateway/jwt_validation_rules\n\n# 4. Set schema validation action\nPUT /zones/{zone_id}/api_gateway/settings/schema_validation\n{\"validation_default_mitigation_action\": \"block\"}\n```\n\n## Progressive Rollout\n\n```\n1. Log mode: Observe false positives\n - Schema: Action = Log\n - JWT: Action = Log\n\n2. Block subset: Protect critical endpoints\n - Change specific endpoint actions to Block\n - Monitor firewall events\n\n3. Full enforcement: Block all violations\n - Change default action to Block\n - Handle fallthrough with custom rule\n```\n\n## BOLA Detection\n\n### Enumeration Detection\nDetects sequential resource access (e.g., `/users/1`, `/users/2`, `/users/3`).\n\n```javascript\n// Block BOLA enumeration attempts\n(cf.api_gateway.cf-risk-bola-enumeration and http.host eq \"api.example.com\")\n// Action: Block or Challenge\n```\n\n### Parameter Pollution\nDetects duplicate/excessive parameters in requests.\n\n```javascript\n// Block parameter pollution\n(cf.api_gateway.cf-risk-bola-pollution and http.host eq \"api.example.com\")\n// Action: Block\n```\n\n### Combined BOLA Protection\n```javascript\n// Comprehensive BOLA rule\n(cf.api_gateway.cf-risk-bola-enumeration or cf.api_gateway.cf-risk-bola-pollution)\nand http.host eq \"api.example.com\"\n// Action: Block\n```\n\n## Authentication Posture\n\n### Detect Missing Auth\n```javascript\n// Log endpoints lacking authentication\n(cf.api_gateway.cf-risk-missing-auth and http.host eq \"api.example.com\")\n// Action: Log (for audit)\n```\n\n### Detect Mixed Auth\n```javascript\n// Alert on inconsistent auth patterns\n(cf.api_gateway.cf-risk-mixed-auth and http.host eq \"api.example.com\")\n// Action: Log (review required)\n```\n\n## Fallthrough Detection (Shadow APIs)\n\n```javascript\n// WAF Custom Rule\n(cf.api_gateway.fallthrough_triggered and http.host eq \"api.example.com\")\n// Action: Log (discover unknown) or Block (strict)\n```\n\n## Rate Limiting by User\n\n```javascript\n// Rate Limiting Rule (modern syntax)\n(http.host eq \"api.example.com\" and\n is_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0]))\n\n// Rate: 100 req/60s\n// Counting expression: lookup_json_string(http.request.jwt.payload[\"{config_id}\"][0], \"sub\")\n```\n\n## Volumetric Abuse Response\n\n```javascript\n// Detect abnormal traffic spikes\n(cf.api_gateway.volumetric_abuse_detected and http.host eq \"api.example.com\")\n// Action: Challenge or Rate Limit\n\n// Combined with rate limiting\n(cf.api_gateway.volumetric_abuse_detected or\n cf.threat_score gt 50) and http.host eq \"api.example.com\"\n// Action: JS Challenge\n```\n\n## GraphQL Protection\n\n```javascript\n// Block oversized queries\n(http.request.uri.path eq \"/graphql\" and\n cf.api_gateway.graphql_query_size gt 100000)\n// Action: Block\n\n// Block deep nested queries\n(http.request.uri.path eq \"/graphql\" and\n cf.api_gateway.graphql_query_depth gt 10)\n// Action: Block\n```\n\n## Architecture Patterns\n\n**Public API:** Discovery + Schema Validation 2.0 + JWT + Rate Limiting + Bot Management \n**Partner API:** mTLS + Schema Validation + Sequence Mitigation \n**Internal API:** Discovery + Schema Learning + Auth Posture\n\n## OWASP API Security Top 10 Mapping (2026)\n\n| OWASP Issue | API Shield Solutions |\n|-------------|---------------------|\n| API1:2023 Broken Object Level Authorization | **BOLA Detection** (enumeration + pollution), Sequence mitigation, Schema, JWT, Rate Limiting |\n| API2:2023 Broken Authentication | **Auth Posture**, mTLS, JWT validation, Bot Management |\n| API3:2023 Broken Object Property Auth | Schema validation, JWT validation |\n| API4:2023 Unrestricted Resource Access | Rate Limiting, **Volumetric Abuse Detection**, **GraphQL Protection**, Bot Management |\n| API5:2023 Broken Function Level Auth | Schema validation, JWT validation, Auth Posture |\n| API6:2023 Unrestricted Business Flows | Sequence mitigation, Bot Management |\n| API7:2023 SSRF | Schema validation, WAF managed rules |\n| API8:2023 Security Misconfiguration | **Schema Validation 2.0**, Auth Posture, WAF rules |\n| API9:2023 Improper Inventory Management | **API Discovery**, Schema learning, Auth Posture |\n| API10:2023 Unsafe API Consumption | JWT validation, Schema validation, WAF managed |\n\n## Monitoring\n\n**Security Events:** `Security > Events` → Filter: Action = block, Service = API Shield \n**Firewall Analytics:** `Analytics > Security` → Filter by `cf.api_gateway.*` fields \n**Logpush fields:** APIGatewayAuthIDPresent, APIGatewayRequestViolatesSchema, APIGatewayFallthroughDetected, JWTValidationResult\n\n## Availability (2026)\n\n| Feature | Availability | Notes |\n|---------|-------------|-------|\n| mTLS (CF-managed CA) | All plans | Self-service |\n| Endpoint Management | All plans | Limited operations |\n| Schema Validation 2.0 | All plans | Limited operations |\n| API Discovery | Enterprise | 10K+ ops |\n| JWT Validation | Enterprise add-on | Full validation |\n| BOLA Detection | Enterprise add-on | Requires session IDs |\n| Auth Posture | Enterprise add-on | Security audit |\n| Volumetric Abuse Detection | Enterprise add-on | Traffic analysis |\n| GraphQL Protection | Enterprise add-on | Query limits |\n| Sequence Mitigation | Enterprise (beta) | Contact team |\n| Full Suite | Enterprise add-on | All features |\n\n**Enterprise limits:** 10K operations (contact for higher). Preview access available for non-contract evaluation.\n\n## See Also\n\n- [configuration.md](configuration.md) - Setup all features before creating rules\n- [api.md](api.md) - Firewall field reference and API endpoints\n- [gotchas.md](gotchas.md) - Common issues and limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/argo-smart-routing/README.md", "content": "# Cloudflare Argo Smart Routing Skill Reference\n\n## Overview\n\nCloudflare Argo Smart Routing is a performance optimization service that detects real-time network issues and routes web traffic across the most efficient network path. It continuously monitors network conditions and intelligently routes traffic through the fastest, most reliable routes in Cloudflare's network.\n\n**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product for enhanced DDoS protection and performance. Existing Argo customers maintain full functionality with gradual migration to Smart Shield features.\n\n## Quick Start\n\n### Enable via cURL\n```bash\ncurl -X PATCH \"https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"value\": \"on\"}'\n```\n\n### Enable via TypeScript SDK\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });\n\nconst result = await client.argo.smartRouting.edit({\n zone_id: 'your-zone-id',\n value: 'on',\n});\n\nconsole.log(`Argo enabled: ${result.value}`);\n```\n\n## Core Concepts\n\n### What It Does\n- **Intelligent routing**: Detects congestion, outages, packet loss in real-time\n- **Global optimization**: Routes across 300+ Cloudflare data centers\n- **Automatic failover**: Switches paths when issues detected (typically <1s)\n- **Works with existing setup**: No origin changes required\n\n### Billing Model\n- Usage-based: Charged per GB of traffic (excluding DDoS/WAF mitigated traffic)\n- Requires billing configuration before enabling\n- Available on Enterprise+ plans (check zone eligibility)\n\n### When to Use\n- **High-traffic production sites** with global user base\n- **Latency-sensitive applications** (APIs, real-time services)\n- **Sites behind Cloudflare proxy** (orange-clouded DNS records)\n- **Combined with Tiered Cache** for maximum performance gains\n\n### When NOT to Use\n- Development/staging environments (cost control)\n- Low-traffic sites (<1TB/month) where cost may exceed benefit\n- Sites with primarily single-region traffic\n\n## Should I Enable Argo?\n\n| Your Situation | Recommendation |\n|----------------|----------------|\n| Global production app, >1TB/month traffic | ✅ Enable - likely ROI positive |\n| Enterprise plan, latency-critical APIs | ✅ Enable - performance matters |\n| Regional site, <100GB/month traffic | ⚠️ Evaluate - cost may not justify |\n| Development/staging environment | ❌ Disable - use in production only |\n| Not yet configured billing | ❌ Configure billing first |\n\n## Reading Order by Task\n\n| Your Goal | Start With | Then Read |\n|-----------|------------|-----------|\n| Enable Argo for first time | Quick Start above → [configuration.md](configuration.md) | [gotchas.md](gotchas.md) |\n| Use TypeScript/Python SDK | [api.md](api.md) | [patterns.md](patterns.md) |\n| Terraform/IaC setup | [configuration.md](configuration.md) | - |\n| Enable for Spectrum TCP app | [patterns.md](patterns.md) → Spectrum section | [api.md](api.md) |\n| Troubleshoot enablement issue | [gotchas.md](gotchas.md) | [api.md](api.md) |\n| Manage billing/usage | [patterns.md](patterns.md) → Billing section | [gotchas.md](gotchas.md) |\n\n## In This Reference\n\n- **[api.md](api.md)** - API endpoints, SDK methods, error handling, Python/TypeScript examples\n- **[configuration.md](configuration.md)** - Terraform setup, environment config, billing configuration\n- **[patterns.md](patterns.md)** - Tiered Cache integration, Spectrum TCP apps, billing management, validation patterns\n- **[gotchas.md](gotchas.md)** - Common errors, permission issues, limits, best practices\n\n## See Also\n\n- [Cloudflare Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)\n- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)\n- [Spectrum Documentation](https://developers.cloudflare.com/spectrum/)\n- [Tiered Cache](https://developers.cloudflare.com/cache/how-to/tiered-cache/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/argo-smart-routing/api.md", "content": "## API Reference\n\n**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product. API endpoints remain stable; existing integrations continue to work without changes.\n\n### Base Endpoint\n```\nhttps://api.cloudflare.com/client/v4\n```\n\n### Authentication\nUse API tokens with Zone:Argo Smart Routing:Edit permissions:\n\n```bash\n# Headers required\nX-Auth-Email: user@example.com\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n### Get Argo Smart Routing Status\n\n**Endpoint:** `GET /zones/{zone_id}/argo/smart_routing`\n\n**Description:** Retrieves current Argo Smart Routing enablement status.\n\n**cURL Example:**\n```bash\ncurl -X GET \"https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\"\n```\n\n**Response:**\n```json\n{\n \"result\": {\n \"id\": \"smart_routing\",\n \"value\": \"on\",\n \"editable\": true,\n \"modified_on\": \"2024-01-11T12:00:00Z\"\n },\n \"success\": true,\n \"errors\": [],\n \"messages\": []\n}\n```\n\n**TypeScript SDK Example:**\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN\n});\n\nconst status = await client.argo.smartRouting.get({ zone_id: 'your-zone-id' });\nconsole.log(`Argo status: ${status.value}, editable: ${status.editable}`);\n```\n\n**Python SDK Example:**\n```python\nfrom cloudflare import Cloudflare\n\nclient = Cloudflare(api_token=os.environ.get('CLOUDFLARE_API_TOKEN'))\n\nstatus = client.argo.smart_routing.get(zone_id='your-zone-id')\nprint(f\"Argo status: {status.value}, editable: {status.editable}\")\n```\n\n### Update Argo Smart Routing Status\n\n**Endpoint:** `PATCH /zones/{zone_id}/argo/smart_routing`\n\n**Description:** Enable or disable Argo Smart Routing for a zone.\n\n**Request Body:**\n```json\n{\n \"value\": \"on\" // or \"off\"\n}\n```\n\n**cURL Example:**\n```bash\ncurl -X PATCH \"https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"value\": \"on\"}'\n```\n\n**TypeScript SDK Example:**\n```typescript\nconst result = await client.argo.smartRouting.edit({\n zone_id: 'your-zone-id',\n value: 'on',\n});\nconsole.log(`Updated: ${result.value} at ${result.modified_on}`);\n```\n\n**Python SDK Example:**\n```python\nresult = client.argo.smart_routing.edit(\n zone_id='your-zone-id',\n value='on'\n)\nprint(f\"Updated: {result.value} at {result.modified_on}\")\n```\n\n## Checking Editability Before Updates\n\n**Critical:** Always check the `editable` field before attempting to enable/disable Argo. When `editable: false`, the zone has restrictions (billing not configured, insufficient permissions, or plan limitations).\n\n**Pattern:**\n```typescript\nasync function safelyEnableArgo(client: Cloudflare, zoneId: string): Promise {\n const status = await client.argo.smartRouting.get({ zone_id: zoneId });\n \n if (!status.editable) {\n console.error('Cannot modify Argo: editable=false (check billing/permissions)');\n return false;\n }\n \n if (status.value === 'on') {\n console.log('Argo already enabled');\n return true;\n }\n \n await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });\n console.log('Argo enabled successfully');\n return true;\n}\n```\n\n**Python Pattern:**\n```python\ndef safely_enable_argo(client: Cloudflare, zone_id: str) -> bool:\n status = client.argo.smart_routing.get(zone_id=zone_id)\n \n if not status.editable:\n print('Cannot modify Argo: editable=false (check billing/permissions)')\n return False\n \n if status.value == 'on':\n print('Argo already enabled')\n return True\n \n client.argo.smart_routing.edit(zone_id=zone_id, value='on')\n print('Argo enabled successfully')\n return True\n```\n\n## Error Handling\n\nThe TypeScript SDK provides typed error classes for robust error handling:\n\n```typescript\nimport Cloudflare from 'cloudflare';\nimport { APIError, APIConnectionError, RateLimitError } from 'cloudflare';\n\nasync function enableArgoWithErrorHandling(client: Cloudflare, zoneId: string) {\n try {\n const result = await client.argo.smartRouting.edit({\n zone_id: zoneId,\n value: 'on',\n });\n return result;\n } catch (error) {\n if (error instanceof RateLimitError) {\n console.error('Rate limited. Retry after:', error.response?.headers.get('retry-after'));\n // Implement exponential backoff\n } else if (error instanceof APIError) {\n console.error('API error:', error.status, error.message);\n if (error.status === 403) {\n console.error('Permission denied - check API token scopes');\n } else if (error.status === 400) {\n console.error('Bad request - verify zone_id and payload');\n }\n } else if (error instanceof APIConnectionError) {\n console.error('Connection failed:', error.message);\n // Retry with exponential backoff\n } else {\n console.error('Unexpected error:', error);\n }\n throw error;\n }\n}\n```\n\n**Python Error Handling:**\n```python\nfrom cloudflare import Cloudflare, APIError, RateLimitError\n\ndef enable_argo_with_error_handling(client: Cloudflare, zone_id: str):\n try:\n result = client.argo.smart_routing.edit(zone_id=zone_id, value='on')\n return result\n except RateLimitError as e:\n print(f\"Rate limited. Retry after: {e.response.headers.get('retry-after')}\")\n raise\n except APIError as e:\n print(f\"API error: {e.status} - {e.message}\")\n if e.status == 403:\n print('Permission denied - check API token scopes')\n elif e.status == 400:\n print('Bad request - verify zone_id and payload')\n raise\n except Exception as e:\n print(f\"Unexpected error: {e}\")\n raise\n```\n\n## Response Schema\n\nAll Argo Smart Routing API responses follow this structure:\n\n```typescript\ninterface ArgoSmartRoutingResponse {\n result: {\n id: 'smart_routing';\n value: 'on' | 'off';\n editable: boolean;\n modified_on: string; // ISO 8601 timestamp\n };\n success: boolean;\n errors: Array<{\n code: number;\n message: string;\n }>;\n messages: Array;\n}\n```\n\n## Key Response Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `value` | `\"on\" \\| \"off\"` | Current enablement status |\n| `editable` | `boolean` | Whether changes are allowed (check before PATCH) |\n| `modified_on` | `string` | ISO timestamp of last modification |\n| `success` | `boolean` | Whether request succeeded |\n| `errors` | `Array` | Error details if `success: false`" }, { "path": "skills/.curated/cloudflare-deploy/references/argo-smart-routing/configuration.md", "content": "## Configuration Management\n\n**Note on Smart Shield Evolution:** Argo Smart Routing is being integrated into Smart Shield. Configuration methods below remain valid; Terraform and IaC patterns unchanged.\n\n### Infrastructure as Code (Terraform)\n\n```hcl\n# terraform/argo.tf\n# Note: Use Cloudflare Terraform provider\n\nresource \"cloudflare_argo\" \"example\" {\n zone_id = var.zone_id\n smart_routing = \"on\"\n tiered_caching = \"on\"\n}\n\nvariable \"zone_id\" {\n description = \"Cloudflare Zone ID\"\n type = string\n}\n\noutput \"argo_enabled\" {\n value = cloudflare_argo.example.smart_routing\n description = \"Argo Smart Routing status\"\n}\n```\n\n### Environment-Based Configuration\n\n```typescript\n// config/argo.ts\ninterface ArgoEnvironmentConfig {\n enabled: boolean;\n tieredCache: boolean;\n monitoring: {\n usageAlerts: boolean;\n threshold: number;\n };\n}\n\nconst configs: Record = {\n production: {\n enabled: true,\n tieredCache: true,\n monitoring: {\n usageAlerts: true,\n threshold: 1000, // GB\n },\n },\n staging: {\n enabled: true,\n tieredCache: false,\n monitoring: {\n usageAlerts: false,\n threshold: 100, // GB\n },\n },\n development: {\n enabled: false,\n tieredCache: false,\n monitoring: {\n usageAlerts: false,\n threshold: 0,\n },\n },\n};\n\nexport function getArgoConfig(env: string): ArgoEnvironmentConfig {\n return configs[env] || configs.development;\n}\n```\n\n### Pulumi Configuration\n\n```typescript\n// pulumi/argo.ts\nimport * as cloudflare from '@pulumi/cloudflare';\n\nconst zone = new cloudflare.Zone('example-zone', {\n zone: 'example.com',\n plan: 'enterprise',\n});\n\nconst argoSettings = new cloudflare.Argo('argo-config', {\n zoneId: zone.id,\n smartRouting: 'on',\n tieredCaching: 'on',\n});\n\nexport const argoEnabled = argoSettings.smartRouting;\nexport const zoneId = zone.id;\n```\n\n## Billing Configuration\n\nBefore enabling Argo Smart Routing, ensure billing is configured for the account:\n\n**Prerequisites:**\n1. Valid payment method on file\n2. Enterprise or higher plan\n3. Zone must have billing enabled\n\n**Check Billing Status via Dashboard:**\n1. Navigate to Account → Billing\n2. Verify payment method configured\n3. Check zone subscription status\n\n**Note:** Attempting to enable Argo without billing configured will result in `editable: false` in API responses.\n\n## Environment Variable Setup\n\n**Required Environment Variables:**\n```bash\n# .env\nCLOUDFLARE_API_TOKEN=your_api_token_here\nCLOUDFLARE_ZONE_ID=your_zone_id_here\nCLOUDFLARE_ACCOUNT_ID=your_account_id_here\n\n# Optional\nARGO_ENABLED=true\nARGO_TIERED_CACHE=true\n```\n\n**TypeScript Configuration Loader:**\n```typescript\n// config/env.ts\nimport { z } from 'zod';\n\nconst envSchema = z.object({\n CLOUDFLARE_API_TOKEN: z.string().min(1),\n CLOUDFLARE_ZONE_ID: z.string().min(1),\n CLOUDFLARE_ACCOUNT_ID: z.string().min(1),\n ARGO_ENABLED: z.string().optional().default('false'),\n ARGO_TIERED_CACHE: z.string().optional().default('false'),\n});\n\nexport const env = envSchema.parse(process.env);\n\nexport const argoConfig = {\n enabled: env.ARGO_ENABLED === 'true',\n tieredCache: env.ARGO_TIERED_CACHE === 'true',\n};\n```\n\n## CI/CD Integration\n\n**GitHub Actions Example:**\n```yaml\n# .github/workflows/deploy-argo.yml\nname: Deploy Argo Configuration\n\non:\n push:\n branches: [main]\n paths:\n - 'terraform/argo.tf'\n\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n \n - name: Setup Terraform\n uses: hashicorp/setup-terraform@v2\n \n - name: Terraform Init\n run: terraform init\n working-directory: ./terraform\n \n - name: Terraform Apply\n run: terraform apply -auto-approve\n working-directory: ./terraform\n env:\n CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n TF_VAR_zone_id: ${{ secrets.CLOUDFLARE_ZONE_ID }}\n```\n\n## Enterprise Preview Program\n\nFor early access to Argo Smart Routing features and Smart Shield integration:\n\n**Eligibility:**\n- Enterprise plan customers\n- Active Cloudflare support contract\n- Production traffic >100GB/month\n\n**How to Join:**\n1. Contact Cloudflare account team or support\n2. Request Argo/Smart Shield preview access\n3. Receive preview zone configuration\n\n**Preview Features:**\n- Enhanced analytics and reporting\n- Smart Shield DDoS integration\n- Advanced routing policies\n- Priority support for routing issues" }, { "path": "skills/.curated/cloudflare-deploy/references/argo-smart-routing/gotchas.md", "content": "## Best Practices Summary\n\n**Smart Shield Note:** Argo Smart Routing evolving into Smart Shield. Best practices below remain applicable; monitor Cloudflare changelog for Smart Shield updates.\n\n1. **Always check editability** before attempting to enable/disable Argo\n2. **Set up billing notifications** to avoid unexpected costs\n3. **Combine with Tiered Cache** for maximum performance benefit\n4. **Use in production only** - disable for dev/staging to control costs\n5. **Monitor analytics** - require 500+ requests in 48h for detailed metrics\n6. **Handle errors gracefully** - check for billing, permissions, zone compatibility\n7. **Test configuration changes** in staging before production\n8. **Use TypeScript SDK** for type safety and better developer experience\n9. **Implement retry logic** for API calls in production systems\n10. **Document zone-specific settings** for team visibility\n\n## Common Errors\n\n### \"Argo unavailable\"\n\n**Problem:** API returns error \"Argo Smart Routing is unavailable for this zone\"\n\n**Cause:** Zone not eligible or billing not set up\n\n**Solution:**\n1. Verify zone has Enterprise or higher plan\n2. Check billing is configured in Account → Billing\n3. Ensure payment method is valid and current\n4. Contact Cloudflare support if eligibility unclear\n\n### \"Cannot enable/disable\"\n\n**Problem:** API call succeeds but status remains unchanged, or `editable: false` in GET response\n\n**Cause:** Insufficient permissions or zone restrictions\n\n**Solution:**\n1. Check API token has `Zone:Argo Smart Routing:Edit` permission\n2. Verify `editable: true` in GET response before attempting PATCH\n3. If `editable: false`, check:\n - Billing configured for account\n - Zone plan includes Argo (Enterprise+)\n - No active zone holds or suspensions\n - API token has correct scopes\n\n### `editable: false` Error\n\n**Problem:** GET request returns `\"editable\": false`, preventing enable/disable\n\n**Cause:** Zone-level restrictions from billing, plan, or permissions\n\n**Solution Pattern:**\n```typescript\nconst status = await client.argo.smartRouting.get({ zone_id: zoneId });\n\nif (!status.editable) {\n // Don't attempt to modify - will fail\n console.error('Cannot modify Argo settings:');\n console.error('- Check billing is configured');\n console.error('- Verify zone has Enterprise+ plan');\n console.error('- Confirm API token has Edit permission');\n throw new Error('Argo is not editable for this zone');\n}\n\n// Safe to proceed with enable/disable\nawait client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });\n```\n\n### Rate Limiting\n\n**Problem:** `429 Too Many Requests` error from API\n\n**Cause:** Exceeded API rate limits (typically 1200 requests per 5 minutes)\n\n**Solution:**\n```typescript\nimport { RateLimitError } from 'cloudflare';\n\ntry {\n await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });\n} catch (error) {\n if (error instanceof RateLimitError) {\n const retryAfter = error.response?.headers.get('retry-after');\n console.log(`Rate limited. Retry after ${retryAfter} seconds`);\n \n // Implement exponential backoff\n await new Promise(resolve => setTimeout(resolve, (retryAfter || 60) * 1000));\n // Retry request\n }\n}\n```\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Min requests for analytics | 500 in 48h | For detailed metrics via GraphQL |\n| Zones supported | Enterprise+ | Check zone plan in dashboard |\n| Billing requirement | Must be configured | Before enabling; verify payment method |\n| API rate limit | 1200 req / 5 min | Per API token across all endpoints |\n| Spectrum apps | No hard limit | Each app can enable Argo independently |\n| Traffic counting | Proxied only | Only orange-clouded DNS records count |\n| DDoS/WAF exemption | Yes | Mitigated traffic excluded from billing |\n| Analytics latency | 1-5 minutes | Real-time metrics not available |\n\n## Additional Resources\n\n- [Official Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)\n- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)\n- [API Authentication](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)\n- [Cloudflare TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)\n- [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/argo-smart-routing/patterns.md", "content": "# Integration Patterns\n\n## Enable Argo + Tiered Cache\n\n```typescript\nasync function enableOptimalPerformance(client: Cloudflare, zoneId: string) {\n await Promise.all([\n client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),\n client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),\n ]);\n}\n```\n\n**Flow:** Visitor → Edge (Lower-Tier) → [Cache Miss] → Upper-Tier → [Cache Miss + Argo] → Origin\n\n**Impact:** Argo ~30% latency reduction + Tiered Cache 50-80% origin offload\n\n## Usage Analytics (GraphQL)\n\n```graphql\nquery ArgoAnalytics($zoneTag: string!) {\n viewer {\n zones(filter: { zoneTag: $zoneTag }) {\n httpRequestsAdaptiveGroups(limit: 1000) {\n sum { argoBytes, bytes }\n }\n }\n }\n}\n```\n\n**Billing:** ~$0.10/GB. DDoS-mitigated and WAF-blocked traffic NOT charged.\n\n## Spectrum TCP Integration\n\nEnable Argo for non-HTTP traffic (databases, game servers, IoT):\n\n```typescript\n// Update existing app\nawait client.spectrum.apps.update(appId, { zone_id: zoneId, argo_smart_routing: true });\n\n// Create new app with Argo\nawait client.spectrum.apps.create({\n zone_id: zoneId,\n dns: { type: 'CNAME', name: 'tcp.example.com' },\n origin_direct: ['tcp://origin.example.com:3306'],\n protocol: 'tcp/3306',\n argo_smart_routing: true,\n});\n```\n\n**Use cases:** MySQL/PostgreSQL (3306/5432), game servers, MQTT (1883), SSH (22)\n\n## Pre-Flight Validation\n\n```typescript\nasync function validateArgoEligibility(client: Cloudflare, zoneId: string) {\n const status = await client.argo.smartRouting.get({ zone_id: zoneId });\n const zone = await client.zones.get({ zone_id: zoneId });\n \n const issues: string[] = [];\n if (!status.editable) issues.push('Zone not editable');\n if (['free', 'pro'].includes(zone.plan.legacy_id)) issues.push('Requires Business+ plan');\n if (zone.status !== 'active') issues.push('Zone not active');\n \n return { canEnable: issues.length === 0, issues };\n}\n```\n\n## Post-Enable Verification\n\n```typescript\nasync function verifyArgoEnabled(client: Cloudflare, zoneId: string): Promise {\n await new Promise(r => setTimeout(r, 2000)); // Wait for propagation\n const status = await client.argo.smartRouting.get({ zone_id: zoneId });\n return status.value === 'on';\n}\n```\n\n## Full Setup Pattern\n\n```typescript\nasync function setupArgo(client: Cloudflare, zoneId: string) {\n // 1. Validate\n const { canEnable, issues } = await validateArgoEligibility(client, zoneId);\n if (!canEnable) throw new Error(issues.join(', '));\n \n // 2. Enable both features\n await Promise.all([\n client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),\n client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),\n ]);\n \n // 3. Verify\n const [argo, cache] = await Promise.all([\n client.argo.smartRouting.get({ zone_id: zoneId }),\n client.argo.tieredCaching.get({ zone_id: zoneId }),\n ]);\n \n return { argo: argo.value === 'on', tieredCache: cache.value === 'on' };\n}\n```\n\n**When to combine:** High-traffic sites (>1TB/mo), global users, cacheable content.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bindings/README.md", "content": "# Cloudflare Bindings Skill Reference\n\nExpert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources.\n\n## What Are Bindings?\n\nBindings are how Workers access Cloudflare resources (storage, compute, services) via the `env` object. They're configured in `wrangler.jsonc`, type-safe via TypeScript, and zero-overhead at runtime.\n\n## Reading Order\n\n1. **This file** - Binding catalog and selection guide\n2. **[api.md](api.md)** - TypeScript types and env access patterns\n3. **[configuration.md](configuration.md)** - Complete wrangler.jsonc examples\n4. **[patterns.md](patterns.md)** - Best practices and common patterns\n5. **[gotchas.md](gotchas.md)** - Critical pitfalls and troubleshooting\n\n## Binding Catalog\n\n### Storage Bindings\n\n| Binding | Use Case | Access Pattern |\n|---------|----------|----------------|\n| **KV** | Key-value cache, CDN-backed reads | `env.MY_KV.get(key)` |\n| **R2** | Object storage (S3-compatible) | `env.MY_BUCKET.get(key)` |\n| **D1** | SQL database (SQLite) | `env.DB.prepare(sql).all()` |\n| **Durable Objects** | Coordination, real-time state | `env.MY_DO.get(id)` |\n| **Vectorize** | Vector embeddings search | `env.VECTORIZE.query(vector)` |\n| **Queues** | Async message processing | `env.MY_QUEUE.send(msg)` |\n\n### Compute Bindings\n\n| Binding | Use Case | Access Pattern |\n|---------|----------|----------------|\n| **Service** | Worker-to-Worker RPC | `env.MY_SERVICE.fetch(req)` |\n| **Workers AI** | LLM inference | `env.AI.run(model, input)` |\n| **Browser Rendering** | Headless Chrome | `env.BROWSER.fetch(url)` |\n\n### Platform Bindings\n\n| Binding | Use Case | Access Pattern |\n|---------|----------|----------------|\n| **Analytics Engine** | Custom metrics | `env.ANALYTICS.writeDataPoint(data)` |\n| **mTLS** | Client certificates | `env.MY_CERT` (string) |\n| **Hyperdrive** | Database pooling | `env.HYPERDRIVE.connectionString` |\n| **Rate Limiting** | Request throttling | `env.RATE_LIMITER.limit(id)` |\n| **Workflows** | Long-running workflows | `env.MY_WORKFLOW.create()` |\n\n### Configuration Bindings\n\n| Binding | Use Case | Access Pattern |\n|---------|----------|----------------|\n| **Environment Variables** | Non-sensitive config | `env.API_URL` (string) |\n| **Secrets** | Sensitive values | `env.API_KEY` (string) |\n| **Text/Data Blobs** | Static files | `env.MY_BLOB` (string) |\n| **WASM** | WebAssembly modules | `env.MY_WASM` (WebAssembly.Module) |\n\n## Quick Selection Guide\n\n**Need persistent storage?**\n- Key-value < 25MB → **KV**\n- Files/objects → **R2**\n- Relational data → **D1**\n- Real-time coordination → **Durable Objects**\n\n**Need AI/compute?**\n- LLM inference → **Workers AI**\n- Scraping/PDFs → **Browser Rendering**\n- Call another Worker → **Service binding**\n\n**Need async processing?**\n- Background jobs → **Queues**\n\n**Need config?**\n- Public values → **Environment Variables**\n- Secrets → **Secrets** (never commit)\n\n## Quick Start\n\n1. **Add binding to wrangler.jsonc:**\n```jsonc\n{\n \"kv_namespaces\": [\n { \"binding\": \"MY_KV\", \"id\": \"your-kv-id\" }\n ]\n}\n```\n\n2. **Generate types:**\n```bash\nnpx wrangler types\n```\n\n3. **Access in Worker:**\n```typescript\nexport default {\n async fetch(request, env, ctx) {\n await env.MY_KV.put('key', 'value');\n return new Response('OK');\n }\n}\n```\n\n## Type Safety\n\nBindings are fully typed via `wrangler types`. See [api.md](api.md) for details.\n\n## Limits\n\n- 64 bindings max per Worker (all types combined)\n- See [gotchas.md](gotchas.md) for per-binding limits\n\n## Key Concepts\n\n**Zero-overhead access:** Bindings compiled into Worker, no network calls to access\n**Type-safe:** Full TypeScript support via `wrangler types`\n**Per-environment:** Different IDs for dev/staging/production\n**Secrets vs Vars:** Secrets encrypted at rest, never in config files\n\n## See Also\n\n- [Cloudflare Docs: Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/)\n- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bindings/api.md", "content": "# Bindings API Reference\n\n## TypeScript Types\n\nCloudflare generates binding types via `npx wrangler types`. This creates `.wrangler/types/runtime.d.ts` with your Env interface.\n\n### Generated Env Interface\n\nAfter running `wrangler types`, TypeScript knows your bindings:\n\n```typescript\ninterface Env {\n // From wrangler.jsonc bindings\n MY_KV: KVNamespace;\n MY_BUCKET: R2Bucket;\n DB: D1Database;\n MY_SERVICE: Fetcher;\n AI: Ai;\n \n // From vars\n API_URL: string;\n \n // From secrets (set via wrangler secret put)\n API_KEY: string;\n}\n```\n\n### Binding Types\n\n| Config | TypeScript Type | Package |\n|--------|-----------------|---------|\n| `kv_namespaces` | `KVNamespace` | `@cloudflare/workers-types` |\n| `r2_buckets` | `R2Bucket` | `@cloudflare/workers-types` |\n| `d1_databases` | `D1Database` | `@cloudflare/workers-types` |\n| `durable_objects.bindings` | `DurableObjectNamespace` | `@cloudflare/workers-types` |\n| `vectorize` | `VectorizeIndex` | `@cloudflare/workers-types` |\n| `queues.producers` | `Queue` | `@cloudflare/workers-types` |\n| `services` | `Fetcher` | `@cloudflare/workers-types` |\n| `ai` | `Ai` | `@cloudflare/workers-types` |\n| `browser` | `Fetcher` | `@cloudflare/workers-types` |\n| `analytics_engine_datasets` | `AnalyticsEngineDataset` | `@cloudflare/workers-types` |\n| `hyperdrive` | `Hyperdrive` | `@cloudflare/workers-types` |\n| `rate_limiting` | `RateLimit` | `@cloudflare/workers-types` |\n| `workflows` | `Workflow` | `@cloudflare/workers-types` |\n| `mtls_certificates` / `vars` / `text_blobs` / `data_blobs` | `string` | Built-in |\n| `wasm_modules` | `WebAssembly.Module` | Built-in |\n\n## Accessing Bindings\n\n### Method 1: fetch() Handler (Recommended)\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const value = await env.MY_KV.get('key');\n return new Response(value);\n }\n}\n```\n\n**Why:** Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.\n\n### Method 2: Hono Framework\n\n```typescript\nimport { Hono } from 'hono';\n\nconst app = new Hono<{ Bindings: Env }>();\n\napp.get('/', async (c) => {\n const value = await c.env.MY_KV.get('key');\n return c.json({ value });\n});\n\nexport default app;\n```\n\n**Why:** c.env auto-typed, ergonomic for routing-heavy apps.\n\n### Method 3: Module Workers (Legacy)\n\n```typescript\nexport async function handleRequest(request: Request, env: Env): Promise {\n const value = await env.MY_KV.get('key');\n return new Response(value);\n}\n\naddEventListener('fetch', (event) => {\n // env not directly available - requires workarounds\n});\n```\n\n**Avoid:** Use fetch() handler instead (Method 1).\n\n## Type Generation Workflow\n\n### Initial Setup\n\n```bash\n# Install wrangler\nnpm install -D wrangler\n\n# Generate types from wrangler.jsonc\nnpx wrangler types\n```\n\n### After Changing Bindings\n\n```bash\n# Added/modified binding in wrangler.jsonc\nnpx wrangler types\n\n# TypeScript now sees updated Env interface\n```\n\n**Note:** `wrangler types` outputs to `.wrangler/types/runtime.d.ts`. TypeScript picks this up automatically if `@cloudflare/workers-types` is in `tsconfig.json` `\"types\"` array.\n\n## Key Binding Methods\n\n**KV:**\n```typescript\nawait env.MY_KV.get(key, { type: 'json' }); // text|json|arrayBuffer|stream\nawait env.MY_KV.put(key, value, { expirationTtl: 3600 });\nawait env.MY_KV.delete(key);\nawait env.MY_KV.list({ prefix: 'user:' });\n```\n\n**R2:**\n```typescript\nawait env.BUCKET.get(key);\nawait env.BUCKET.put(key, value);\nawait env.BUCKET.delete(key);\nawait env.BUCKET.list({ prefix: 'images/' });\n```\n\n**D1:**\n```typescript\nawait env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\nawait env.DB.batch([stmt1, stmt2]);\n```\n\n**Service:**\n```typescript\nawait env.MY_SERVICE.fetch(new Request('https://fake/path'));\n```\n\n**Workers AI:**\n```typescript\nawait env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });\n```\n\n**Queues:**\n```typescript\nawait env.MY_QUEUE.send({ userId: 123, action: 'process' });\n```\n\n**Durable Objects:**\n```typescript\nconst id = env.MY_DO.idFromName('user-123');\nconst stub = env.MY_DO.get(id);\nawait stub.fetch(new Request('https://fake/increment'));\n```\n\n## Runtime vs Build-Time Types\n\n| Type Source | When Generated | Use Case |\n|-------------|----------------|----------|\n| `@cloudflare/workers-types` | npm install | Base Workers APIs (Request, Response, etc.) |\n| `wrangler types` | After config change | Your specific bindings (Env interface) |\n\n**Install both:**\n```bash\nnpm install -D @cloudflare/workers-types\nnpx wrangler types\n```\n\n## Type Safety Best Practices\n\n1. **Never use `any` for env:**\n```typescript\n// ❌ BAD\nasync fetch(request: Request, env: any) { }\n\n// ✅ GOOD\nasync fetch(request: Request, env: Env) { }\n```\n\n2. **Run wrangler types after config changes:**\n```bash\n# After editing wrangler.jsonc\nnpx wrangler types\n```\n\n3. **Check generated types match config:**\n```bash\n# View generated Env interface\ncat .wrangler/types/runtime.d.ts\n```\n\n## See Also\n\n- [Workers Types Package](https://www.npmjs.com/package/@cloudflare/workers-types)\n- [Wrangler Types Command](https://developers.cloudflare.com/workers/wrangler/commands/#types)" }, { "path": "skills/.curated/cloudflare-deploy/references/bindings/configuration.md", "content": "# Binding Configuration Reference\n\n## Storage Bindings\n\n```jsonc\n{\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"...\" }],\n \"r2_buckets\": [{ \"binding\": \"MY_BUCKET\", \"bucket_name\": \"my-bucket\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"my-db\", \"database_id\": \"...\" }],\n \"durable_objects\": { \"bindings\": [{ \"name\": \"MY_DO\", \"class_name\": \"MyDO\" }] },\n \"vectorize\": [{ \"binding\": \"VECTORIZE\", \"index_name\": \"my-index\" }],\n \"queues\": { \"producers\": [{ \"binding\": \"MY_QUEUE\", \"queue\": \"my-queue\" }] }\n}\n```\n\n**Create commands:**\n```bash\nnpx wrangler kv namespace create MY_KV\nnpx wrangler r2 bucket create my-bucket\nnpx wrangler d1 create my-db\nnpx wrangler vectorize create my-index --dimensions=768 --metric=cosine\nnpx wrangler queues create my-queue\n\n# List existing resources\nnpx wrangler kv namespace list\nnpx wrangler r2 bucket list\nnpx wrangler d1 list\nnpx wrangler vectorize list\nnpx wrangler queues list\n```\n\n## Compute Bindings\n\n```jsonc\n{\n \"services\": [{ \n \"binding\": \"MY_SERVICE\", \n \"service\": \"other-worker\",\n \"environment\": \"production\" // Optional: target specific env\n }],\n \"ai\": { \"binding\": \"AI\" },\n \"browser\": { \"binding\": \"BROWSER\" },\n \"workflows\": [{ \"binding\": \"MY_WORKFLOW\", \"name\": \"my-workflow\" }]\n}\n```\n\n**Create workflows:**\n```bash\nnpx wrangler workflows create my-workflow\n```\n\n## Platform Bindings\n\n```jsonc\n{\n \"analytics_engine_datasets\": [{ \"binding\": \"ANALYTICS\" }],\n \"mtls_certificates\": [{ \"binding\": \"MY_CERT\", \"certificate_id\": \"...\" }],\n \"hyperdrive\": [{ \"binding\": \"HYPERDRIVE\", \"id\": \"...\" }],\n \"unsafe\": {\n \"bindings\": [{ \"name\": \"RATE_LIMITER\", \"type\": \"ratelimit\", \"namespace_id\": \"...\" }]\n }\n}\n```\n\n## Configuration Bindings\n\n```jsonc\n{\n \"vars\": {\n \"API_URL\": \"https://api.example.com\",\n \"MAX_RETRIES\": \"3\"\n },\n \"text_blobs\": { \"MY_TEXT\": \"./data/template.html\" },\n \"data_blobs\": { \"MY_DATA\": \"./data/config.bin\" },\n \"wasm_modules\": { \"MY_WASM\": \"./build/module.wasm\" }\n}\n```\n\n**Secrets (never in config):**\n```bash\nnpx wrangler secret put API_KEY\n```\n\n## Environment-Specific Configuration\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"vars\": { \"ENV\": \"production\" },\n \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"prod-kv-id\" }],\n \n \"env\": {\n \"staging\": {\n \"vars\": { \"ENV\": \"staging\" },\n \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"staging-kv-id\" }]\n }\n }\n}\n```\n\n**Deploy:**\n```bash\nnpx wrangler deploy # Production\nnpx wrangler deploy --env staging\n```\n\n## Local Development\n\n```jsonc\n{\n \"kv_namespaces\": [{\n \"binding\": \"MY_KV\",\n \"id\": \"prod-id\",\n \"preview_id\": \"dev-id\" // Used in wrangler dev\n }]\n}\n```\n\n**Or use remote:**\n```bash\nnpx wrangler dev --remote # Uses production bindings\n```\n\n## Complete Example\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"name\": \"my-app\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \n \"vars\": { \"API_URL\": \"https://api.example.com\" },\n \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"abc123\" }],\n \"r2_buckets\": [{ \"binding\": \"ASSETS\", \"bucket_name\": \"my-assets\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"my-db\", \"database_id\": \"xyz789\" }],\n \"services\": [{ \"binding\": \"AUTH\", \"service\": \"auth-worker\" }],\n \"ai\": { \"binding\": \"AI\" }\n}\n```\n\n## Binding-Specific Configuration\n\n### Durable Objects with Class Export\n\n```jsonc\n{\n \"durable_objects\": {\n \"bindings\": [\n { \"name\": \"COUNTER\", \"class_name\": \"Counter\", \"script_name\": \"my-worker\" }\n ]\n }\n}\n```\n\n```typescript\n// In same Worker or script_name Worker\nexport class Counter {\n constructor(private state: DurableObjectState, private env: Env) {}\n async fetch(request: Request) { /* ... */ }\n}\n```\n\n### Queue Consumers\n\n```jsonc\n{\n \"queues\": {\n \"producers\": [{ \"binding\": \"MY_QUEUE\", \"queue\": \"my-queue\" }],\n \"consumers\": [{ \"queue\": \"my-queue\", \"max_batch_size\": 10 }]\n }\n}\n```\n\nQueue consumer handler: `export default { async queue(batch, env) { /* process batch.messages */ } }`\n\n## Key Points\n\n- **64 binding limit** (all types combined)\n- **Secrets**: Always use `wrangler secret put`, never commit\n- **Types**: Run `npx wrangler types` after config changes\n- **Environments**: Use `env` field for staging/production variants\n- **Development**: Use `preview_id` or `--remote` flag\n- **IDs vs Names**: Some bindings use `id` (KV, D1), others use `name` (R2, Queues)\n\n## See Also\n\n- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)" }, { "path": "skills/.curated/cloudflare-deploy/references/bindings/gotchas.md", "content": "# Binding Gotchas and Troubleshooting\n\n## Critical: Global Scope Mutation\n\n### ❌ THE #1 GOTCHA: Caching env in Global Scope\n\n```typescript\n// ❌ DANGEROUS - env cached at deploy time\nconst apiKey = env.API_KEY; // ERROR: env not available in global scope\n\nexport default {\n async fetch(request: Request, env: Env) {\n // Uses undefined or stale value!\n }\n}\n```\n\n**Why it breaks:**\n- `env` not available in global scope\n- If using workarounds, secrets may not update without redeployment\n- Leads to \"Cannot read property 'X' of undefined\" errors\n\n**✅ Always access env per-request:**\n```typescript\nexport default {\n async fetch(request: Request, env: Env) {\n const apiKey = env.API_KEY; // Fresh every request\n }\n}\n```\n\n## Common Errors\n\n### \"env.MY_KV is undefined\"\n\n**Cause:** Name mismatch or not configured \n**Solution:** Check wrangler.jsonc (case-sensitive), run `npx wrangler types`, verify `npx wrangler kv namespace list`\n\n### \"Property 'MY_KV' does not exist on type 'Env'\"\n\n**Cause:** Types not generated \n**Solution:** `npx wrangler types`\n\n### \"preview_id is required for --remote\"\n\n**Cause:** Missing preview binding \n**Solution:** Add `\"preview_id\": \"dev-id\"` or use `npx wrangler dev` (local mode)\n\n### \"Secret updated but Worker still uses old value\"\n\n**Cause:** Cached in global scope or not redeployed \n**Solution:** Avoid global caching, redeploy after secret change\n\n### \"KV get() returns null for existing key\"\n\n**Cause:** Eventual consistency (60s), wrong namespace, wrong environment \n**Solution:**\n```bash\n# Check key exists\nnpx wrangler kv key get --binding=MY_KV \"your-key\"\n\n# Verify namespace ID\nnpx wrangler kv namespace list\n\n# Check environment\nnpx wrangler deployments list\n```\n\n### \"D1 database not found\"\n\n**Solution:** `npx wrangler d1 list`, verify ID in wrangler.jsonc\n\n### \"Service binding returns 'No such service'\"\n\n**Cause:** Target Worker not deployed, name mismatch, environment mismatch \n**Solution:**\n```bash\n# List deployed Workers\nnpx wrangler deployments list --name=target-worker\n\n# Check service binding config\ncat wrangler.jsonc | grep -A2 services\n\n# Deploy target first\ncd ../target-worker && npx wrangler deploy\n```\n\n### \"Rate limit exceeded\" on KV writes\n\n**Cause:** >1 write/second per key \n**Solution:** Use different keys, Durable Objects, or Queues\n\n## Type Safety Gotchas\n\n### Missing @cloudflare/workers-types\n\n**Error:** `Cannot find name 'Request'` \n**Solution:** `npm install -D @cloudflare/workers-types`, add to tsconfig.json `\"types\"`\n\n### Binding Type Mismatches\n\n```typescript\n// ❌ Wrong - KV returns string | null\nconst value: string = await env.MY_KV.get('key');\n\n// ✅ Handle null\nconst value = await env.MY_KV.get('key');\nif (!value) return new Response('Not found', { status: 404 });\n```\n\n## Environment Gotchas\n\n### Wrong Environment Deployed\n\n**Solution:** Check `npx wrangler deployments list`, use `--env` flag\n\n### Secrets Not Per-Environment\n\n**Solution:** Set per environment: `npx wrangler secret put API_KEY --env staging`\n\n## Development Gotchas\n\n**wrangler dev vs deploy:**\n- dev: Uses `preview_id` or local bindings, secrets not available\n- deploy: Uses production `id`, secrets available\n\n**Access secrets in dev:** `npx wrangler dev --remote` \n**Persist local data:** `npx wrangler dev --persist`\n\n## Performance Gotchas\n\n### Sequential Binding Calls\n\n```typescript\n// ❌ Slow\nconst user = await env.DB.prepare('...').first();\nconst config = await env.MY_KV.get('config');\n\n// ✅ Parallel\nconst [user, config] = await Promise.all([\n env.DB.prepare('...').first(),\n env.MY_KV.get('config')\n]);\n```\n\n## Security Gotchas\n\n**❌ Secrets in logs:** `console.log('Key:', env.API_KEY)` - visible in dashboard \n**✅** `console.log('Key:', env.API_KEY ? '***' : 'missing')`\n\n**❌ Exposing env:** `return Response.json(env)` - exposes all bindings \n**✅** Never return env object in responses\n\n## Limits Reference\n\n| Resource | Limit | Impact | Plan |\n|----------|-------|--------|------|\n| **Bindings per Worker** | 64 total | All binding types combined | All |\n| **Environment variables** | 64 max, 5KB each | Per Worker | All |\n| **Secret size** | 1KB | Per secret | All |\n| **KV key size** | 512 bytes | UTF-8 encoded | All |\n| **KV value size** | 25 MB | Per value | All |\n| **KV writes per key** | 1/second | Per key; exceeding = 429 error | All |\n| **KV list() results** | 1000 keys | Per call; use cursor for more | All |\n| **KV operations** | 1000 reads/day | Free tier only | Free |\n| **R2 object size** | 5 TB | Per object | All |\n| **R2 operations** | 1M Class A/month free | Writes | All |\n| **D1 database size** | 10 GB | Per database | All |\n| **D1 rows per query** | 100,000 | Result set limit | All |\n| **D1 databases** | 10 | Free tier | Free |\n| **Queue batch size** | 100 messages | Per consumer batch | All |\n| **Queue message size** | 128 KB | Per message | All |\n| **Service binding calls** | Unlimited | Counts toward CPU time | All |\n| **Durable Objects** | 1M requests/month free | First 1M | Free |\n\n## Debugging Tips\n\n```bash\n# Check configuration\nnpx wrangler deploy --dry-run # Validate config without deploying\nnpx wrangler kv namespace list # List KV namespaces\nnpx wrangler secret list # List secrets (not values)\nnpx wrangler deployments list # Recent deployments\n\n# Inspect bindings\nnpx wrangler kv key list --binding=MY_KV\nnpx wrangler kv key get --binding=MY_KV \"key-name\"\nnpx wrangler r2 object get my-bucket/file.txt\nnpx wrangler d1 execute my-db --command=\"SELECT * FROM sqlite_master\"\n\n# Test locally\nnpx wrangler dev # Local mode\nnpx wrangler dev --remote # Production bindings\nnpx wrangler dev --persist # Persist data across restarts\n\n# Verify types\nnpx wrangler types\ncat .wrangler/types/runtime.d.ts | grep \"interface Env\"\n\n# Debug specific binding issues\nnpx wrangler tail # Stream logs in real-time\nnpx wrangler tail --format=pretty # Formatted logs\n```\n\n## See Also\n\n- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)\n- [Wrangler Commands](https://developers.cloudflare.com/workers/wrangler/commands/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bindings/patterns.md", "content": "# Binding Patterns and Best Practices\n\n## Service Binding Patterns\n\n### RPC via Service Bindings\n\n```typescript\n// auth-worker\nexport default {\n async fetch(request: Request, env: Env) {\n const token = request.headers.get('Authorization');\n return new Response(JSON.stringify({ valid: await validateToken(token) }));\n }\n}\n\n// api-worker\nconst response = await env.AUTH_SERVICE.fetch(\n new Request('https://fake-host/validate', {\n headers: { 'Authorization': token }\n })\n);\n```\n\n**Why RPC?** Zero latency (same datacenter), no DNS, free, type-safe.\n\n**HTTP vs Service:**\n```typescript\n// ❌ HTTP (slow, paid, cross-region latency)\nawait fetch('https://auth-worker.example.com/validate');\n\n// ✅ Service binding (fast, free, same isolate)\nawait env.AUTH_SERVICE.fetch(new Request('https://fake-host/validate'));\n```\n\n**URL doesn't matter:** Service bindings ignore hostname/protocol, routing happens via binding name.\n\n### Typed Service RPC\n\n```typescript\n// shared-types.ts\nexport interface AuthRequest { token: string; }\nexport interface AuthResponse { valid: boolean; userId?: string; }\n\n// auth-worker\nexport default {\n async fetch(request: Request): Promise {\n const body: AuthRequest = await request.json();\n const response: AuthResponse = { valid: true, userId: '123' };\n return Response.json(response);\n }\n}\n\n// api-worker\nconst response = await env.AUTH_SERVICE.fetch(\n new Request('https://fake/validate', {\n method: 'POST',\n body: JSON.stringify({ token } satisfies AuthRequest)\n })\n);\nconst data: AuthResponse = await response.json();\n```\n\n## Secrets Management\n\n```bash\n# Set secret\nnpx wrangler secret put API_KEY\ncat api-key.txt | npx wrangler secret put API_KEY\nnpx wrangler secret put API_KEY --env staging\n```\n\n```typescript\n// Use secret\nconst response = await fetch('https://api.example.com', {\n headers: { 'Authorization': `Bearer ${env.API_KEY}` }\n});\n```\n\n**Never commit secrets:**\n```jsonc\n// ❌ NEVER\n{ \"vars\": { \"API_KEY\": \"sk_live_abc123\" } }\n```\n\n## Testing with Mock Bindings\n\n### Vitest Mock\n\n```typescript\nimport { vi } from 'vitest';\n\nconst mockKV: KVNamespace = {\n get: vi.fn(async (key) => key === 'test' ? 'value' : null),\n put: vi.fn(async () => {}),\n delete: vi.fn(async () => {}),\n list: vi.fn(async () => ({ keys: [], list_complete: true, cursor: '' })),\n getWithMetadata: vi.fn(),\n} as unknown as KVNamespace;\n\nconst mockEnv: Env = { MY_KV: mockKV };\nconst mockCtx: ExecutionContext = {\n waitUntil: vi.fn(),\n passThroughOnException: vi.fn(),\n};\n\nconst response = await worker.fetch(\n new Request('http://localhost/test'),\n mockEnv,\n mockCtx\n);\n```\n\n## Binding Access Patterns\n\n### Lazy Access\n\n```typescript\n// ✅ Access only when needed\nif (url.pathname === '/cached') {\n const cached = await env.MY_KV.get('data');\n if (cached) return new Response(cached);\n}\n```\n\n### Parallel Access\n\n```typescript\n// ✅ Parallelize independent calls\nconst [user, config, cache] = await Promise.all([\n env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(),\n env.MY_KV.get('config'),\n env.CACHE.get('data')\n]);\n```\n\n## Storage Selection\n\n### KV: CDN-Backed Reads\n\n```typescript\nconst config = await env.MY_KV.get('app-config', { type: 'json' });\n```\n\n**Use when:** Read-heavy, <25MB, global distribution, eventual consistency OK \n**Latency:** <10ms reads (cached), writes eventually consistent (60s)\n\n### D1: Relational Queries\n\n```typescript\nconst results = await env.DB.prepare(`\n SELECT u.name, COUNT(o.id) FROM users u\n LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id\n`).all();\n```\n\n**Use when:** Relational data, JOINs, ACID transactions \n**Limits:** 10GB database size, 100k rows per query\n\n### R2: Large Objects\n\n```typescript\nconst object = await env.MY_BUCKET.get('large-file.zip');\nreturn new Response(object.body);\n```\n\n**Use when:** Files >25MB, S3-compatible API needed \n**Limits:** 5TB per object, unlimited storage\n\n### Durable Objects: Coordination\n\n```typescript\nconst id = env.COUNTER.idFromName('global');\nconst stub = env.COUNTER.get(id);\nawait stub.fetch(new Request('https://fake/increment'));\n```\n\n**Use when:** Strong consistency, real-time coordination, WebSocket state \n**Guarantees:** Single-threaded execution, transactional storage\n\n## Anti-Patterns\n\n**❌ Hardcoding credentials:** `const apiKey = 'sk_live_abc123'` \n**✅** `npx wrangler secret put API_KEY`\n\n**❌ Using REST API:** `fetch('https://api.cloudflare.com/.../kv/...')` \n**✅** `env.MY_KV.get('key')`\n\n**❌ Polling storage:** `setInterval(() => env.KV.get('config'), 1000)` \n**✅** Use Durable Objects for real-time state\n\n**❌ Large data in vars:** `{ \"vars\": { \"HUGE_CONFIG\": \"...\" } }` (5KB max) \n**✅** `env.MY_KV.put('config', data)`\n\n**❌ Caching env globally:** `const apiKey = env.API_KEY` outside fetch() \n**✅** Access `env.API_KEY` per-request inside fetch()\n\n## See Also\n\n- [Service Bindings Docs](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/)\n- [Miniflare Testing](https://miniflare.dev/)" }, { "path": "skills/.curated/cloudflare-deploy/references/bot-management/README.md", "content": "# Cloudflare Bot Management\n\nEnterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.\n\n## Overview\n\nBot Management provides multi-tier protection:\n- **Free (Bot Fight Mode)**: Auto-blocks definite bots, no config\n- **Pro/Business (Super Bot Fight Mode)**: Configurable actions, static resource protection, analytics groupings\n- **Enterprise (Bot Management)**: Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics\n\n## Quick Start\n\n```txt\n# Dashboard: Security > Bots\n# Enterprise: Deploy rule template\n(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block\n(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge\n```\n\n## What Do You Need?\n\n```txt\n├─ Initial setup → configuration.md\n│ ├─ Free tier → \"Bot Fight Mode\"\n│ ├─ Pro/Business → \"Super Bot Fight Mode\"\n│ └─ Enterprise → \"Bot Management for Enterprise\"\n├─ Workers API integration → api.md\n├─ WAF rules → patterns.md\n├─ Debugging → gotchas.md\n└─ Analytics → api.md#bot-analytics\n```\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| Enable bot protection | README → configuration.md |\n| Workers bot detection | README → api.md |\n| WAF rule templates | README → patterns.md |\n| Debug bot issues | gotchas.md |\n| Advanced analytics | api.md#bot-analytics |\n\n## Core Concepts\n\n**Bot Scores**: 1-99 (1 = definitely automated, 99 = definitely human). Threshold: <30 indicates bot traffic. Enterprise gets granular 1-99; Pro/Business get groupings only.\n\n**Detection Engines**: Heuristics (known fingerprints, assigns score=1), ML (majority of detections, supervised learning on billions of requests), Anomaly Detection (optional, baseline traffic analysis), JavaScript Detections (headless browser detection).\n\n**Verified Bots**: Allowlisted good bots (search engines, AI crawlers) verified via reverse DNS or Web Bot Auth. Access via `cf.bot_management.verified_bot` or `cf.verified_bot_category`.\n\n## Platform Limits\n\n| Plan | Bot Scores | JA3/JA4 | Custom Rules | Analytics Retention |\n|------|------------|---------|--------------|---------------------|\n| Free | No (auto-block only) | No | 5 | N/A (no analytics) |\n| Pro/Business | Groupings only | No | 20/100 | 30 days (72h at a time) |\n| Enterprise | 1-99 granular | Yes | 1,000+ | 30 days (1 week at a time) |\n\n## Basic Patterns\n\n```typescript\n// Workers: Check bot score\nexport default {\n async fetch(request: Request): Promise {\n const botScore = request.cf?.botManagement?.score;\n if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {\n return new Response('Bot detected', { status: 403 });\n }\n return fetch(request);\n }\n};\n```\n\n```txt\n# WAF: Block definite bots\n(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)\n\n# WAF: Protect sensitive endpoints\n(cf.bot_management.score lt 50 and http.request.uri.path in {\"/login\" \"/checkout\"} and not cf.bot_management.verified_bot)\n```\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates\n- [api.md](./api.md) - Workers BotManagement interface, WAF fields, JA4 Signals\n- [patterns.md](./patterns.md) - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling\n- [gotchas.md](./gotchas.md) - False positives/negatives, score=0 issues, JSD limitations, CSP requirements\n\n## See Also\n\n- [waf](../waf/) - WAF custom rules for bot enforcement\n- [workers](../workers/) - Workers request.cf.botManagement API\n- [api-shield](../api-shield/) - API-specific bot protection\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bot-management/api.md", "content": "# Bot Management API\n\n## Workers: BotManagement Interface\n\n```typescript\ninterface BotManagement {\n score: number; // 1-99 (Enterprise), 0 if not computed\n verifiedBot: boolean; // Is verified bot\n staticResource: boolean; // Serves static resource\n ja3Hash: string; // JA3 fingerprint (Enterprise, HTTPS only)\n ja4: string; // JA4 fingerprint (Enterprise, HTTPS only)\n jsDetection?: {\n passed: boolean; // Passed JS detection (if enabled)\n };\n detectionIds: number[]; // Heuristic detection IDs\n corporateProxy?: boolean; // From corporate proxy (Enterprise)\n}\n\n// DEPRECATED: Use botManagement.score instead\n// request.cf.clientTrustScore (legacy, duplicate of botManagement.score)\n\n// Access via request.cf\nimport type { IncomingRequestCfProperties } from '@cloudflare/workers-types';\n\nexport default {\n async fetch(request: Request): Promise {\n const cf = request.cf as IncomingRequestCfProperties | undefined;\n const botMgmt = cf?.botManagement;\n \n if (!botMgmt) return fetch(request);\n if (botMgmt.verifiedBot) return fetch(request); // Allow verified bots\n if (botMgmt.score === 1) return new Response('Blocked', { status: 403 });\n if (botMgmt.score < 30) return new Response('Challenge required', { status: 429 });\n \n return fetch(request);\n }\n};\n```\n\n## WAF Fields Reference\n\n```txt\n# Score fields\ncf.bot_management.score # 0-99 (0 = not computed)\ncf.bot_management.verified_bot # boolean\ncf.bot_management.static_resource # boolean\ncf.bot_management.ja3_hash # string (Enterprise)\ncf.bot_management.ja4 # string (Enterprise)\ncf.bot_management.detection_ids # array\ncf.bot_management.js_detection.passed # boolean\ncf.bot_management.corporate_proxy # boolean (Enterprise)\ncf.verified_bot_category # string\n\n# Workers equivalent\nrequest.cf.botManagement.score\nrequest.cf.botManagement.verifiedBot\nrequest.cf.botManagement.ja3Hash\nrequest.cf.botManagement.ja4\nrequest.cf.botManagement.jsDetection.passed\nrequest.cf.verifiedBotCategory\n```\n\n## JA4 Signals (Enterprise)\n\n```typescript\nimport type { IncomingRequestCfProperties } from '@cloudflare/workers-types';\n\ninterface JA4Signals {\n // Ratios (0.0-1.0)\n heuristic_ratio_1h?: number; // Fraction flagged by heuristics\n browser_ratio_1h?: number; // Fraction from real browsers \n cache_ratio_1h?: number; // Fraction hitting cache\n h2h3_ratio_1h?: number; // Fraction using HTTP/2 or HTTP/3\n // Ranks (relative position in distribution)\n uas_rank_1h?: number; // User-Agent diversity rank\n paths_rank_1h?: number; // Path diversity rank\n reqs_rank_1h?: number; // Request volume rank\n ips_rank_1h?: number; // IP diversity rank\n // Quantiles (0.0-1.0, percentile in distribution)\n reqs_quantile_1h?: number; // Request volume quantile\n ips_quantile_1h?: number; // IP count quantile\n}\n\nexport default {\n async fetch(request: Request): Promise {\n const cf = request.cf as IncomingRequestCfProperties | undefined;\n const ja4Signals = cf?.ja4Signals as JA4Signals | undefined;\n \n if (!ja4Signals) return fetch(request); // Not available for HTTP or Worker routing\n \n // Check for anomalous behavior\n // High heuristic_ratio or low browser_ratio = suspicious\n const heuristicRatio = ja4Signals.heuristic_ratio_1h ?? 0;\n const browserRatio = ja4Signals.browser_ratio_1h ?? 0;\n \n if (heuristicRatio > 0.5 || browserRatio < 0.3) {\n return new Response('Suspicious traffic', { status: 403 });\n }\n \n return fetch(request);\n }\n};\n```\n\n## Common Patterns\n\nSee [patterns.md](./patterns.md) for Workers examples: mobile app allowlisting, corporate proxy exemption, datacenter detection, conditional delay, and more.\n\n## Bot Analytics\n\n### Access Locations\n- Dashboard: Security > Bots (old) or Security > Analytics > Bot analysis (new)\n- GraphQL API for programmatic access\n- Security Events & Security Analytics\n- Logpush/Logpull\n\n### Available Data\n- **Enterprise BM**: Bot scores (1-99), bot score source, distribution\n- **Pro/Business**: Bot groupings (automated, likely automated, likely human)\n- Top attributes: IPs, paths, user agents, countries\n- Detection sources: Heuristics, ML, AD, JSD\n- Verified bot categories\n\n### Time Ranges\n- **Enterprise BM**: Up to 1 week at a time, 30 days history\n- **Pro/Business**: Up to 72 hours at a time, 30 days history\n- Real-time in most cases, adaptive sampling (1-10% depending on volume)\n\n## Logpush Fields\n\n```txt\nBotScore # 1-99 or 0 if not computed\nBotScoreSrc # Detection engine (ML, Heuristics, etc.)\nBotTags # Classification tags\nBotDetectionIDs # Heuristic detection IDs\n```\n\n**BotScoreSrc values:**\n- `\"Heuristics\"` - Known fingerprint\n- `\"Machine Learning\"` - ML model\n- `\"Anomaly Detection\"` - Baseline anomaly\n- `\"JS Detection\"` - JavaScript check\n- `\"Cloudflare Service\"` - Zero Trust\n- `\"Not Computed\"` - Score = 0\n\nAccess via Logpush (stream to cloud storage/SIEM), Logpull (API to fetch logs), or GraphQL API (query analytics data).\n\n## Testing with Miniflare\n\nMiniflare provides mock botManagement data for local development:\n\n**Default values:**\n- `score: 99` (human)\n- `verifiedBot: false`\n- `corporateProxy: false`\n- `ja3Hash: \"25b4882c2bcb50cd6b469ff28c596742\"`\n- `staticResource: false`\n- `detectionIds: []`\n\n**Override in tests:**\n```typescript\nimport { getPlatformProxy } from 'wrangler';\n\nconst { cf, dispose } = await getPlatformProxy();\n// cf.botManagement is frozen mock object\nexpect(cf.botManagement.score).toBe(99);\n```\n\nFor custom test data, mock request.cf in your test setup.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bot-management/configuration.md", "content": "# Bot Management Configuration\n\n## Product Tiers\n\n**Note:** Dashboard paths differ between old and new UI:\n- **New:** Security > Settings > Filter \"Bot traffic\"\n- **Old:** Security > Bots\n\nBoth UIs access same settings.\n\n### Bot Score Groupings (Pro/Business)\n\nPro/Business users see bot score groupings instead of granular 1-99 scores:\n\n| Score | Grouping | Meaning |\n|-------|----------|---------|\n| 0 | Not computed | Bot Management didn't run |\n| 1 | Automated | Definite bot (heuristic match) |\n| 2-29 | Likely automated | Probably bot (ML detection) |\n| 30-99 | Likely human | Probably human |\n| N/A | Verified bot | Allowlisted good bot |\n\nEnterprise plans get granular 1-99 scores for custom thresholds.\n\n### Bot Fight Mode (Free)\n- Auto-blocks definite bots (score=1), excludes verified bots by default\n- JavaScript Detections always enabled, no configuration options\n\n### Super Bot Fight Mode (Pro/Business)\n```txt\nDashboard: Security > Bots > Configure\n- Definitely automated: Block/Challenge\n- Likely automated: Challenge/Allow \n- Verified bots: Allow (recommended)\n- Static resource protection: ON (may block mail clients)\n- JavaScript Detections: Optional\n```\n\n### Bot Management for Enterprise\n```txt\nDashboard: Security > Bots > Configure > Auto-updates: ON (recommended)\n\n# Template 1: Block definite bots\n(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)\nAction: Block\n\n# Template 2: Challenge likely bots\n(cf.bot_management.score ge 2 and cf.bot_management.score le 29 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource)\nAction: Managed Challenge\n```\n\n## JavaScript Detections Setup\n\n### Enable via Dashboard\n```txt\nSecurity > Bots > Configure Bot Management > JS Detections: ON\n\nUpdate CSP: script-src 'self' /cdn-cgi/challenge-platform/;\n```\n\n### Manual JS Injection (API)\n```html\n\n\n```\n\n**Use API for**: Selective deployment on specific pages \n**Don't combine**: Zone-wide toggle + manual injection\n\n### WAF Rules for JSD\n```txt\n# NEVER use on first page visit (needs HTML page first)\n(not cf.bot_management.js_detection.passed and http.request.uri.path eq \"/api/user/create\" and http.request.method eq \"POST\" and not cf.bot_management.verified_bot)\nAction: Managed Challenge (always use Managed Challenge, not Block)\n```\n\n### Limitations\n- First request won't have JSD data (needs HTML page first)\n- Strips ETags from HTML responses\n- Not supported with CSP via `` tags\n- Websocket endpoints not supported\n- Native mobile apps won't pass\n- cf_clearance cookie: 15-minute lifespan, max 4096 bytes\n\n## __cf_bm Cookie\n\nCloudflare sets `__cf_bm` cookie to smooth bot scores across user sessions:\n\n- **Purpose:** Reduces false positives from score volatility\n- **Scope:** Per-domain, HTTP-only\n- **Lifespan:** Session duration\n- **Privacy:** No PII—only session classification\n- **Automatic:** No configuration required\n\nBot scores for repeat visitors consider session history via this cookie.\n\n## Static Resource Protection\n\n**File Extensions**: ico, jpg, png, jpeg, gif, css, js, tif, tiff, bmp, pict, webp, svg, svgz, class, jar, txt, csv, doc, docx, xls, xlsx, pdf, ps, pls, ppt, pptx, ttf, otf, woff, woff2, eot, eps, ejs, swf, torrent, midi, mid, m3u8, m4a, mp3, ogg, ts \n**Plus**: `/.well-known/` path (all files)\n\n```txt\n# Exclude static resources from bot rules\n(cf.bot_management.score lt 30 and not cf.bot_management.static_resource)\n```\n\n**WARNING**: May block mail clients fetching static images\n\n## JA3/JA4 Fingerprinting (Enterprise)\n\n```txt\n# Block specific attack fingerprint\n(cf.bot_management.ja3_hash eq \"8b8e3d5e3e8b3d5e\")\n\n# Allow mobile app by fingerprint\n(cf.bot_management.ja4 eq \"your_mobile_app_fingerprint\")\n```\n\nOnly available for HTTPS/TLS traffic. Missing for Worker-routed traffic or HTTP requests.\n\n## Verified Bot Categories\n\n```txt\n# Allow search engines only\n(cf.verified_bot_category eq \"Search Engine Crawler\")\n\n# Block AI crawlers\n(cf.verified_bot_category eq \"AI Crawler\")\nAction: Block\n\n# Or use dashboard: Security > Settings > Bot Management > Block AI Bots\n```\n\n| Category | String Value | Example |\n|----------|--------------|---------|\n| AI Crawler | `AI Crawler` | GPTBot, Claude-Web |\n| AI Assistant | `AI Assistant` | Perplexity-User, DuckAssistBot |\n| AI Search | `AI Search` | OAI-SearchBot |\n| Accessibility | `Accessibility` | Accessible Web Bot |\n| Academic Research | `Academic Research` | Library of Congress |\n| Advertising & Marketing | `Advertising & Marketing` | Google Adsbot |\n| Aggregator | `Aggregator` | Pinterest, Indeed |\n| Archiver | `Archiver` | Internet Archive, CommonCrawl |\n| Feed Fetcher | `Feed Fetcher` | RSS/Podcast updaters |\n| Monitoring & Analytics | `Monitoring & Analytics` | Uptime monitors |\n| Page Preview | `Page Preview` | Facebook/Slack link preview |\n| SEO | `Search Engine Optimization` | Google Lighthouse |\n| Security | `Security` | Vulnerability scanners |\n| Social Media Marketing | `Social Media Marketing` | Brandwatch |\n| Webhooks | `Webhooks` | Payment processors |\n| Other | `Other` | Uncategorized bots |\n\n## Best Practices\n\n- **ML Auto-Updates**: Enable on Enterprise for latest models\n- **Start with Managed Challenge**: Test before blocking\n- **Always exclude verified bots**: Use `not cf.bot_management.verified_bot`\n- **Exempt corporate proxies**: For B2B traffic via `cf.bot_management.corporate_proxy`\n- **Use static resource exception**: Improves performance, reduces overhead\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bot-management/gotchas.md", "content": "# Bot Management Gotchas\n\n## Common Errors\n\n### \"Bot Score = 0\"\n\n**Cause:** Bot Management didn't run (internal Cloudflare request, Worker routing to zone (Orange-to-Orange), or request handled before BM (Redirect Rules, etc.)) \n**Solution:** Check request flow and ensure Bot Management runs in request lifecycle\n\n### \"JavaScript Detections Not Working\"\n\n**Cause:** `js_detection.passed` always false or undefined due to: CSP headers don't allow `/cdn-cgi/challenge-platform/`, using on first page visit (needs HTML page first), ad blockers or disabled JS, JSD not enabled in dashboard, or using Block action (must use Managed Challenge) \n**Solution:** Add CSP header `Content-Security-Policy: script-src 'self' /cdn-cgi/challenge-platform/;` and ensure JSD is enabled with Managed Challenge action\n\n### \"False Positives (Legitimate Users Blocked)\"\n\n**Cause:** Bot detection incorrectly flagging legitimate users \n**Solution:** Check Bot Analytics for affected IPs/paths, identify detection source (ML, Heuristics, etc.), create exception rule like `(cf.bot_management.score lt 30 and http.request.uri.path eq \"/problematic-path\")` with Action: Skip (Bot Management), or allowlist by IP/ASN/country\n\n### \"False Negatives (Bots Not Caught)\"\n\n**Cause:** Bots bypassing detection \n**Solution:** Lower score threshold (30 → 50), enable JavaScript Detections, add JA3/JA4 fingerprinting rules, or use rate limiting as fallback\n\n### \"Verified Bot Blocked\"\n\n**Cause:** Search engine bot blocked by WAF Managed Rules (not just Bot Management) \n**Solution:** Create WAF exception for specific rule ID and verify bot via reverse DNS\n\n### \"Yandex Bot Blocked During IP Update\"\n\n**Cause:** Yandex updates bot IPs; new IPs unrecognized for 48h during propagation \n**Solution:** \n1. Check Security Events for specific WAF rule ID blocking Yandex\n2. Create WAF exception:\n ```txt\n (http.user_agent contains \"YandexBot\" and ip.src in {})\n Action: Skip (WAF Managed Ruleset)\n ```\n3. Monitor Bot Analytics for 48h\n4. Remove exception after propagation completes\n\nIssue resolves automatically after 48h. Contact Cloudflare Support if persists.\n\n### \"JA3/JA4 Missing\"\n\n**Cause:** Non-HTTPS traffic, Worker routing traffic, Orange-to-Orange traffic via Worker, or Bot Management skipped \n**Solution:** JA3/JA4 only available for HTTPS/TLS traffic; check request routing\n\n**JA3/JA4 Not User-Unique:** Same browser/library version = same fingerprint\n- Don't use for user identification\n- Use for client profiling only\n- Fingerprints change with browser updates\n\n## Bot Verification Methods\n\nCloudflare verifies bots via:\n\n1. **Reverse DNS (IP validation):** Traditional method—bot IP resolves to expected domain\n2. **Web Bot Auth:** Modern cryptographic verification—faster propagation\n\nWhen `verifiedBot=true`, bot passed at least one method.\n\n**Inactive verified bots:** IPs removed after 24h of no traffic.\n\n## Detection Engine Behavior\n\n| Engine | Score | Timing | Plan | Notes |\n|--------|-------|--------|------|-------|\n| Heuristics | Always 1 | Immediate | All | Known fingerprints—overrides ML |\n| ML | 1-99 | Immediate | All | Majority of detections |\n| Anomaly Detection | Influences | After baseline | Enterprise | Optional, baseline analysis |\n| JavaScript Detections | Pass/fail | After JS | Pro+ | Headless browser detection |\n| Cloudflare Service | N/A | N/A | Enterprise | Zero Trust internal source |\n\n**Priority:** Heuristics > ML—if heuristic matches, score=1 regardless of ML.\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Bot Score = 0 | Means not computed | Not score = 100 |\n| First request JSD data | May not be available | JSD data appears on subsequent requests |\n| Score accuracy | Not 100% guaranteed | False positives/negatives possible |\n| JSD on first HTML page visit | Not supported | Requires subsequent page load |\n| JSD requirements | JavaScript-enabled browser | Won't work with JS disabled or ad blockers |\n| JSD ETag stripping | Strips ETags from HTML responses | May affect caching behavior |\n| JSD CSP compatibility | Requires specific CSP | Not compatible with some CSP configurations |\n| JSD meta CSP tags | Not supported | Must use HTTP headers |\n| JSD WebSocket support | Not supported | WebSocket endpoints won't work with JSD |\n| JSD mobile app support | Native apps won't pass | Only works in browsers |\n| JA3/JA4 traffic type | HTTPS/TLS only | Not available for non-HTTPS traffic |\n| JA3/JA4 Worker routing | Missing for Worker-routed traffic | Check request routing |\n| JA3/JA4 uniqueness | Not unique per user | Shared by clients with same browser/library |\n| JA3/JA4 stability | Can change with updates | Browser/library updates affect fingerprints |\n| WAF custom rules (Free) | 5 | Varies by plan |\n| WAF custom rules (Pro) | 20 | Varies by plan |\n| WAF custom rules (Business) | 100 | Varies by plan |\n| WAF custom rules (Enterprise) | 1,000+ | Varies by plan |\n| Workers CPU time | Varies by plan | Applies to bot logic |\n| Bot Analytics sampling | 1-10% adaptive | High-volume zones sampled more aggressively |\n| Bot Analytics history | 30 days max | Historical data retention limit |\n| CSP requirements for JSD | Must allow `/cdn-cgi/challenge-platform/` | Required for JSD to function |\n\n### Plan Restrictions\n\n| Feature | Free | Pro/Business | Enterprise |\n|---------|------|--------------|------------|\n| Granular scores (1-99) | No | No | Yes |\n| JA3/JA4 | No | No | Yes |\n| Anomaly Detection | No | No | Yes |\n| Corporate Proxy detection | No | No | Yes |\n| Verified bot categories | Limited | Limited | Full |\n| Custom WAF rules | 5 | 20/100 | 1,000+ |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/bot-management/patterns.md", "content": "# Bot Management Patterns\n\n## E-commerce Protection\n\n```txt\n# High security for checkout\n(cf.bot_management.score lt 50 and http.request.uri.path in {\"/checkout\" \"/cart/add\"} and not cf.bot_management.verified_bot and not cf.bot_management.corporate_proxy)\nAction: Managed Challenge\n```\n\n## API Protection\n\n```txt\n# Protect API with JS detection + score\n(http.request.uri.path matches \"^/api/\" and (cf.bot_management.score lt 30 or not cf.bot_management.js_detection.passed) and not cf.bot_management.verified_bot)\nAction: Block\n```\n\n## SEO-Friendly Bot Handling\n\n```txt\n# Allow search engine crawlers\n(cf.bot_management.score lt 30 and not cf.verified_bot_category in {\"Search Engine Crawler\"})\nAction: Managed Challenge\n```\n\n## Block AI Scrapers\n\n```txt\n# Block training crawlers only (allow AI assistants/search)\n(cf.verified_bot_category eq \"AI Crawler\")\nAction: Block\n\n# Block all AI-related bots (training + assistants + search)\n(cf.verified_bot_category in {\"AI Crawler\" \"AI Assistant\" \"AI Search\"})\nAction: Block\n\n# Allow AI Search, block AI Crawler and AI Assistant\n(cf.verified_bot_category in {\"AI Crawler\" \"AI Assistant\"})\nAction: Block\n\n# Or use dashboard: Security > Settings > Bot Management > Block AI Bots\n```\n\n## Rate Limiting by Bot Score\n\n```txt\n# Stricter limits for suspicious traffic\n(cf.bot_management.score lt 50)\nRate: 10 requests per 10 seconds\n\n(cf.bot_management.score ge 50)\nRate: 100 requests per 10 seconds\n```\n\n## Mobile App Allowlisting\n\n```txt\n# Identify mobile app by JA3/JA4\n(cf.bot_management.ja4 in {\"fingerprint1\" \"fingerprint2\"})\nAction: Skip (all remaining rules)\n```\n\n## Datacenter Detection\n\n```typescript\nimport type { IncomingRequestCfProperties } from '@cloudflare/workers-types';\n\n// Low score + not corporate proxy = likely datacenter bot\nexport default {\n async fetch(request: Request): Promise {\n const cf = request.cf as IncomingRequestCfProperties | undefined;\n const botMgmt = cf?.botManagement;\n \n if (botMgmt?.score && botMgmt.score < 30 && \n !botMgmt.corporateProxy && !botMgmt.verifiedBot) {\n return new Response('Datacenter traffic blocked', { status: 403 });\n }\n \n return fetch(request);\n }\n};\n```\n\n## Conditional Delay (Tarpit)\n\n```typescript\nimport type { IncomingRequestCfProperties } from '@cloudflare/workers-types';\n\n// Add delay proportional to bot suspicion\nexport default {\n async fetch(request: Request): Promise {\n const cf = request.cf as IncomingRequestCfProperties | undefined;\n const botMgmt = cf?.botManagement;\n \n if (botMgmt?.score && botMgmt.score < 50 && !botMgmt.verifiedBot) {\n // Delay: 0-2 seconds for scores 50-0\n const delayMs = Math.max(0, (50 - botMgmt.score) * 40);\n await new Promise(r => setTimeout(r, delayMs));\n }\n \n return fetch(request);\n }\n};\n```\n\n## Layered Defense\n\n```txt\n1. Bot Management (score-based)\n2. JavaScript Detections (for JS-capable clients)\n3. Rate Limiting (fallback protection)\n4. WAF Managed Rules (OWASP, etc.)\n```\n\n## Progressive Enhancement\n\n```txt\nPublic content: High threshold (score < 10)\nAuthenticated: Medium threshold (score < 30)\nSensitive: Low threshold (score < 50) + JSD\n```\n\n## Zero Trust for Bots\n\n```txt\n1. Default deny (all scores < 30)\n2. Allowlist verified bots\n3. Allowlist mobile apps (JA3/JA4)\n4. Allowlist corporate proxies\n5. Allowlist static resources\n```\n\n## Workers: Score + JS Detection\n\n```typescript\nimport type { IncomingRequestCfProperties } from '@cloudflare/workers-types';\n\nexport default {\n async fetch(request: Request): Promise {\n const cf = request.cf as IncomingRequestCfProperties | undefined;\n const botMgmt = cf?.botManagement;\n const url = new URL(request.url);\n \n if (botMgmt?.staticResource) return fetch(request); // Skip static\n \n // API endpoints: require JS detection + good score\n if (url.pathname.startsWith('/api/')) {\n const jsDetectionPassed = botMgmt?.jsDetection?.passed ?? false;\n const score = botMgmt?.score ?? 100;\n \n if (!jsDetectionPassed || score < 30) {\n return new Response('Unauthorized', { status: 401 });\n }\n }\n \n return fetch(request);\n }\n};\n```\n\n## Rate Limiting by JWT Claim + Bot Score\n\n```txt\n# Enterprise: Combine bot score with JWT validation\nRate limiting > Custom rules\n- Field: lookup_json_string(http.request.jwt.claims[\"{config_id}\"][0], \"sub\")\n- Matches: user ID claim\n- Additional condition: cf.bot_management.score lt 50\n```\n\n## WAF Integration Points\n\n- **WAF Custom Rules**: Primary enforcement mechanism\n- **Rate Limiting Rules**: Bot score as dimension, stricter limits for low scores\n- **Transform Rules**: Pass score to origin via custom header\n- **Workers**: Programmatic bot logic, custom scoring algorithms\n- **Page Rules / Configuration Rules**: Zone-level overrides, path-specific settings\n\n## See Also\n\n- [gotchas.md](./gotchas.md) - Common errors, false positives/negatives, limitations\n" }, { "path": "skills/.curated/cloudflare-deploy/references/browser-rendering/README.md", "content": "# Cloudflare Browser Rendering Skill Reference\n\n**Description**: Expert knowledge for Cloudflare Browser Rendering - control headless Chrome on Cloudflare's global network for browser automation, screenshots, PDFs, web scraping, testing, and content generation.\n\n**When to use**: Any task involving Cloudflare Browser Rendering including: taking screenshots, generating PDFs, web scraping, browser automation, testing web applications, extracting structured data, capturing page metrics, or automating browser interactions.\n\n## Decision Tree\n\n### REST API vs Workers Bindings\n\n**Use REST API when:**\n- One-off, stateless tasks (screenshot, PDF, content fetch)\n- No Workers infrastructure yet\n- Simple integrations from external services\n- Need quick prototyping without deployment\n\n**Use Workers Bindings when:**\n- Complex browser automation workflows\n- Need session reuse for performance\n- Multiple page interactions per request\n- Custom scripting and logic required\n- Building production applications\n\n### Puppeteer vs Playwright\n\n| Feature | Puppeteer | Playwright |\n|---------|-----------|------------|\n| API Style | Chrome DevTools Protocol | High-level abstractions |\n| Selectors | CSS, XPath | CSS, text, role, test-id |\n| Best for | Advanced control, CDP access | Quick automation, testing |\n| Learning curve | Steeper | Gentler |\n\n**Use Puppeteer:** Need CDP protocol access, Chrome-specific features, migration from existing Puppeteer code\n**Use Playwright:** Modern selector APIs, cross-browser patterns, faster development\n\n## Tier Limits Summary\n\n| Limit | Free Tier | Paid Tier |\n|-------|-----------|-----------|\n| Daily browser time | 10 minutes | Unlimited* |\n| Concurrent sessions | 3 | 30 |\n| Requests per minute | 6 | 180 |\n\n*Subject to fair-use policy. See [gotchas.md](gotchas.md) for details.\n\n## Reading Order\n\n**New to Browser Rendering:**\n1. [configuration.md](configuration.md) - Setup and deployment\n2. [patterns.md](patterns.md) - Common use cases with examples\n3. [api.md](api.md) - API reference\n4. [gotchas.md](gotchas.md) - Avoid common pitfalls\n\n**Specific task:**\n- **Setup/deployment** → [configuration.md](configuration.md)\n- **API reference/endpoints** → [api.md](api.md)\n- **Example code/patterns** → [patterns.md](patterns.md)\n- **Debugging/troubleshooting** → [gotchas.md](gotchas.md)\n\n**REST API users:**\n- Start with [api.md](api.md) REST API section\n- Check [gotchas.md](gotchas.md) for rate limits\n\n**Workers users:**\n- Start with [configuration.md](configuration.md)\n- Review [patterns.md](patterns.md) for session management\n- Reference [api.md](api.md) for Workers Bindings\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, wrangler config, compatibility\n- **[api.md](api.md)** - REST API endpoints + Workers Bindings (Puppeteer/Playwright)\n- **[patterns.md](patterns.md)** - Common patterns, use cases, real examples\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, tier limits, common errors\n\n## See Also\n\n- [Cloudflare Docs](https://developers.cloudflare.com/browser-rendering/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/browser-rendering/api.md", "content": "# Browser Rendering API\n\n## REST API\n\n**Base:** `https://api.cloudflare.com/client/v4/accounts/{accountId}/browser-rendering` \n**Auth:** `Authorization: Bearer ` (Browser Rendering - Edit permission)\n\n### Endpoints\n\n| Endpoint | Description | Key Options |\n|----------|-------------|-------------|\n| `/content` | Get rendered HTML | `url`, `waitUntil` |\n| `/screenshot` | Capture image | `screenshotOptions: {type, fullPage, clip}` |\n| `/pdf` | Generate PDF | `pdfOptions: {format, landscape, margin}` |\n| `/snapshot` | HTML + inlined resources | `url` |\n| `/scrape` | Extract by selectors | `selectors: [\"h1\", \".price\"]` |\n| `/json` | AI-structured extraction | `schema: {name: \"string\", price: \"number\"}` |\n| `/links` | Get all links | `url` |\n| `/markdown` | Convert to markdown | `url` |\n\n```bash\ncurl -X POST '.../browser-rendering/screenshot' \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d '{\"url\":\"https://example.com\",\"screenshotOptions\":{\"fullPage\":true}}'\n```\n\n## Workers Binding\n\n```jsonc\n// wrangler.jsonc\n{ \"browser\": { \"binding\": \"MYBROWSER\" } }\n```\n\n## Puppeteer\n\n```typescript\nimport puppeteer from \"@cloudflare/puppeteer\";\n\nconst browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 });\nconst page = await browser.newPage();\nawait page.goto('https://example.com', { waitUntil: 'networkidle0' });\n\n// Content\nconst html = await page.content();\nconst title = await page.title();\n\n// Screenshot/PDF\nawait page.screenshot({ fullPage: true, type: 'png' });\nawait page.pdf({ format: 'A4', printBackground: true });\n\n// Interaction\nawait page.click('#button');\nawait page.type('#input', 'text');\nawait page.evaluate(() => document.querySelector('h1')?.textContent);\n\n// Session management\nconst sessions = await puppeteer.sessions(env.MYBROWSER);\nconst limits = await puppeteer.limits(env.MYBROWSER);\n\nawait browser.close();\n```\n\n## Playwright\n\n```typescript\nimport { launch, connect } from \"@cloudflare/playwright\";\n\nconst browser = await launch(env.MYBROWSER, { keep_alive: 600000 });\nconst page = await browser.newPage();\n\nawait page.goto('https://example.com', { waitUntil: 'networkidle' });\n\n// Modern selectors\nawait page.locator('.button').click();\nawait page.getByText('Submit').click();\nawait page.getByTestId('search').fill('query');\n\n// Context for isolation\nconst context = await browser.newContext({\n viewport: { width: 1920, height: 1080 },\n userAgent: 'custom'\n});\n\nawait browser.close();\n```\n\n## Session Management\n\n```typescript\n// List sessions\nawait puppeteer.sessions(env.MYBROWSER);\n\n// Connect to existing\nawait puppeteer.connect(env.MYBROWSER, sessionId);\n\n// Check limits\nawait puppeteer.limits(env.MYBROWSER);\n// { remaining: ms, total: ms, concurrent: n }\n```\n\n## Key Options\n\n| Option | Values |\n|--------|--------|\n| `waitUntil` | `load`, `domcontentloaded`, `networkidle0`, `networkidle2` |\n| `keep_alive` | Max 600000ms (10 min) |\n| `screenshot.type` | `png`, `jpeg` |\n| `pdf.format` | `A4`, `Letter`, `Legal` |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/browser-rendering/configuration.md", "content": "# Configuration & Setup\n\n## Installation\n\n```bash\nnpm install @cloudflare/puppeteer # or @cloudflare/playwright\n```\n\n**Use Cloudflare packages** - standard `puppeteer`/`playwright` won't work in Workers.\n\n## wrangler.json\n\n```json\n{\n \"name\": \"browser-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"browser\": {\n \"binding\": \"MYBROWSER\"\n }\n}\n```\n\n**Required:** `nodejs_compat` flag and `browser.binding`.\n\n## TypeScript\n\n```typescript\ninterface Env {\n MYBROWSER: Fetcher;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // ...\n }\n} satisfies ExportedHandler;\n```\n\n## Development\n\n```bash\nwrangler dev --remote # --remote required for browser binding\n```\n\n**Local mode does NOT support Browser Rendering** - must use `--remote`.\n\n## REST API\n\nNo wrangler config needed. Get API token with \"Browser Rendering - Edit\" permission.\n\n```bash\ncurl -X POST \\\n 'https://api.cloudflare.com/client/v4/accounts/{accountId}/browser-rendering/screenshot' \\\n -H 'Authorization: Bearer TOKEN' \\\n -d '{\"url\": \"https://example.com\"}' --output screenshot.png\n```\n\n## Requirements\n\n| Requirement | Value |\n|-------------|-------|\n| Node.js compatibility | `nodejs_compat` flag |\n| Compatibility date | 2023-03-01+ |\n| Module format | ES modules only |\n| Browser | Chromium 119+ (no Firefox/Safari) |\n\n**Not supported:** WebGL, WebRTC, extensions, `file://` protocol, Service Worker syntax.\n\n## Troubleshooting\n\n| Error | Solution |\n|-------|----------|\n| `MYBROWSER is undefined` | Use `wrangler dev --remote` |\n| `nodejs_compat not enabled` | Add to `compatibility_flags` |\n| `Module not found` | `npm install @cloudflare/puppeteer` |\n| `Browser Rendering not available` | Enable in dashboard |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/browser-rendering/gotchas.md", "content": "# Browser Rendering Gotchas\n\n## Tier Limits\n\n| Limit | Free | Paid |\n|-------|------|------|\n| Daily browser time | 10 min | Unlimited* |\n| Concurrent sessions | 3 | 30 |\n| Requests/minute | 6 | 180 |\n| Session keep-alive | 10 min max | 10 min max |\n\n*Subject to fair-use policy.\n\n**Check quota:**\n```typescript\nconst limits = await puppeteer.limits(env.MYBROWSER);\n// { remaining: 540000, total: 600000, concurrent: 2 }\n```\n\n## Always Close Browsers\n\n```typescript\nconst browser = await puppeteer.launch(env.MYBROWSER);\ntry {\n const page = await browser.newPage();\n await page.goto(\"https://example.com\");\n return new Response(await page.content());\n} finally {\n await browser.close(); // ALWAYS in finally\n}\n```\n\n**Workers vs REST:** REST auto-closes after timeout. Workers must call `close()` or session stays open until `keep_alive` expires.\n\n## Optimize Concurrency\n\n```typescript\n// ❌ 3 sessions (hits free tier limit)\nconst browser1 = await puppeteer.launch(env.MYBROWSER);\nconst browser2 = await puppeteer.launch(env.MYBROWSER);\n\n// ✅ 1 session, multiple pages\nconst browser = await puppeteer.launch(env.MYBROWSER);\nconst page1 = await browser.newPage();\nconst page2 = await browser.newPage();\n```\n\n## Common Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| Session limit exceeded | Too many concurrent | Close unused browsers, use pages not browsers |\n| Page navigation timeout | Slow page or `networkidle` on busy page | Increase timeout, use `waitUntil: \"load\"` |\n| Session not found | Expired session | Catch error, launch new session |\n| Evaluation failed | DOM element missing | Use `?.` optional chaining |\n| Protocol error: Target closed | Page closed during operation | Await all ops before closing |\n\n## page.evaluate() Gotchas\n\n```typescript\n// ❌ Outer scope not available\nconst selector = \"h1\";\nawait page.evaluate(() => document.querySelector(selector));\n\n// ✅ Pass as argument\nawait page.evaluate((sel) => document.querySelector(sel)?.textContent, selector);\n```\n\n## Performance\n\n**waitUntil options (fastest to slowest):**\n1. `domcontentloaded` - DOM ready\n2. `load` - load event (default)\n3. `networkidle0` - no network for 500ms\n\n**Block unnecessary resources:**\n```typescript\nawait page.setRequestInterception(true);\npage.on(\"request\", (req) => {\n if ([\"image\", \"stylesheet\", \"font\"].includes(req.resourceType())) {\n req.abort();\n } else {\n req.continue();\n }\n});\n```\n\n**Session reuse:** Cold start ~1-2s, warm connect ~100-200ms. Store sessionId in KV for reuse.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/browser-rendering/patterns.md", "content": "# Browser Rendering Patterns\n\n## Basic Worker\n\n```typescript\nimport puppeteer from \"@cloudflare/puppeteer\";\n\nexport default {\n async fetch(request, env) {\n const browser = await puppeteer.launch(env.MYBROWSER);\n try {\n const page = await browser.newPage();\n await page.goto(\"https://example.com\");\n return new Response(await page.content());\n } finally {\n await browser.close(); // ALWAYS in finally\n }\n }\n};\n```\n\n## Session Reuse\n\nKeep sessions alive for performance:\n```typescript\nlet sessionId = await env.SESSION_KV.get(\"browser-session\");\nif (sessionId) {\n browser = await puppeteer.connect(env.MYBROWSER, sessionId);\n} else {\n browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 });\n await env.SESSION_KV.put(\"browser-session\", browser.sessionId(), { expirationTtl: 600 });\n}\n// Don't close browser to keep session alive\n```\n\n## Common Operations\n\n| Task | Code |\n|------|------|\n| Screenshot | `await page.screenshot({ type: \"png\", fullPage: true })` |\n| PDF | `await page.pdf({ format: \"A4\", printBackground: true })` |\n| Extract data | `await page.evaluate(() => document.querySelector('h1').textContent)` |\n| Fill form | `await page.type('#input', 'value'); await page.click('button')` |\n| Wait nav | `await Promise.all([page.waitForNavigation(), page.click('a')])` |\n\n## Parallel Scraping\n\n```typescript\nconst pages = await Promise.all(urls.map(() => browser.newPage()));\nawait Promise.all(pages.map((p, i) => p.goto(urls[i])));\nconst titles = await Promise.all(pages.map(p => p.title()));\n```\n\n## Playwright Selectors\n\n```typescript\nimport { launch } from \"@cloudflare/playwright\";\nconst browser = await launch(env.MYBROWSER);\nawait page.getByRole(\"button\", { name: \"Sign in\" }).click();\nawait page.getByLabel(\"Email\").fill(\"user@example.com\");\nawait page.getByTestId(\"submit-button\").click();\n```\n\n## Incognito Contexts\n\nIsolated sessions without multiple browsers:\n```typescript\nconst ctx1 = await browser.createIncognitoBrowserContext();\nconst ctx2 = await browser.createIncognitoBrowserContext();\n// Each has isolated cookies/storage\n```\n\n## Quota Check\n\n```typescript\nconst limits = await puppeteer.limits(env.MYBROWSER);\nif (limits.remaining < 60000) return new Response(\"Quota low\", { status: 429 });\n```\n\n## Error Handling\n\n```typescript\ntry {\n await page.goto(url, { timeout: 30000, waitUntil: \"networkidle0\" });\n} catch (e) {\n if (e.message.includes(\"timeout\")) return new Response(\"Timeout\", { status: 504 });\n if (e.message.includes(\"Session limit\")) return new Response(\"Too many sessions\", { status: 429 });\n} finally {\n if (browser) await browser.close();\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/c3/README.md", "content": "# C3 (create-cloudflare)\n\nOfficial CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment.\n\n## Quick Start\n\n```bash\n# Interactive (recommended for first-time)\nnpm create cloudflare@latest my-app\n\n# Worker (API/WebSocket/Cron)\nnpm create cloudflare@latest my-api -- --type=hello-world --ts\n\n# Pages (static/SSG/full-stack)\nnpm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages\n```\n\n## Platform Decision Tree\n\n```\nWhat are you building?\n\n├─ API / WebSocket / Cron / Email handler\n│ └─ Workers (default) - no --platform flag needed\n│ npm create cloudflare@latest my-api -- --type=hello-world\n\n├─ Static site / SSG / Documentation\n│ └─ Pages - requires --platform=pages\n│ npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages\n\n├─ Full-stack app (Next.js/Remix/SvelteKit)\n│ ├─ Need Durable Objects, Queues, or Workers-only features?\n│ │ └─ Workers (default)\n│ └─ Otherwise use Pages for git integration and branch previews\n│ └─ Add --platform=pages\n\n└─ Convert existing project\n └─ npm create cloudflare@latest . -- --type=pre-existing --existing-script=./src/worker.ts\n```\n\n**Critical:** Pages projects require `--platform=pages` flag. Without it, C3 defaults to Workers.\n\n## Interactive Flow\n\nWhen run without flags, C3 prompts in this order:\n\n1. **Project name** - Directory to create (defaults to current dir with `.`)\n2. **Application type** - `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template`\n3. **Platform** - `workers` (default) or `pages` (for web apps only)\n4. **Framework** - If web-app: `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, etc.\n5. **TypeScript** - `yes` (recommended) or `no`\n6. **Git** - Initialize repository? `yes` or `no`\n7. **Deploy** - Deploy now? `yes` or `no` (requires `wrangler login`)\n\n## Installation Methods\n\n```bash\n# NPM\nnpm create cloudflare@latest\n\n# Yarn\nyarn create cloudflare\n\n# PNPM\npnpm create cloudflare@latest\n```\n\n## In This Reference\n\n| File | Purpose | Use When |\n|------|---------|----------|\n| **api.md** | Complete CLI flag reference | Scripting, CI/CD, advanced usage |\n| **configuration.md** | Generated files, bindings, types | Understanding output, customization |\n| **patterns.md** | Workflows, CI/CD, monorepos | Real-world integration |\n| **gotchas.md** | Troubleshooting failures | Deployment blocked, errors |\n\n## Reading Order\n\n| Task | Read |\n|------|------|\n| Create first project | README only |\n| Set up CI/CD | README → api → patterns |\n| Debug failed deploy | gotchas |\n| Understand generated files | configuration |\n| Full CLI reference | api |\n| Create custom template | patterns → configuration |\n| Convert existing project | README → patterns |\n\n## Post-Creation\n\n```bash\ncd my-app\n\n# Local dev with hot reload\nnpm run dev\n\n# Generate TypeScript types for bindings\nnpm run cf-typegen\n\n# Deploy to Cloudflare\nnpm run deploy\n```\n\n## See Also\n\n- **workers/README.md** - Workers runtime, bindings, APIs\n- **workers-ai/README.md** - AI/ML models\n- **pages/README.md** - Pages-specific features\n- **wrangler/README.md** - Wrangler CLI beyond initial setup\n- **d1/README.md** - SQLite database\n- **r2/README.md** - Object storage\n" }, { "path": "skills/.curated/cloudflare-deploy/references/c3/api.md", "content": "# C3 CLI Reference\n\n## Invocation\n\n```bash\nnpm create cloudflare@latest [name] [-- flags] # NPM requires --\nyarn create cloudflare [name] [flags]\npnpm create cloudflare@latest [name] [-- flags]\n```\n\n## Core Flags\n\n| Flag | Values | Description |\n|------|--------|-------------|\n| `--type` | `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template` | Application type |\n| `--platform` | `workers` (default), `pages` | Target platform |\n| `--framework` | `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, `qwik`, `vue`, `angular`, `hono` | Web framework (requires `--type=web-app`) |\n| `--lang` | `ts`, `js`, `python` | Language (for `--type=hello-world`) |\n| `--ts` / `--no-ts` | - | TypeScript for web apps |\n\n## Deployment Flags\n\n| Flag | Description |\n|------|-------------|\n| `--deploy` / `--no-deploy` | Deploy immediately (prompts interactive, skips in CI) |\n| `--git` / `--no-git` | Initialize git (default: yes) |\n| `--open` | Open browser after deploy |\n\n## Advanced Flags\n\n| Flag | Description |\n|------|-------------|\n| `--template=user/repo` | GitHub template or local path |\n| `--existing-script=./src/worker.ts` | Existing script (requires `--type=pre-existing`) |\n| `--category=ai\\|database\\|realtime` | Demo filter (requires `--type=demo`) |\n| `--experimental` | Enable experimental features |\n| `--wrangler-defaults` | Skip wrangler prompts |\n\n## Environment Variables\n\n```bash\nCLOUDFLARE_API_TOKEN=xxx # For deployment\nCLOUDFLARE_ACCOUNT_ID=xxx # Account ID\nCF_TELEMETRY_DISABLED=1 # Disable telemetry\n```\n\n## Exit Codes\n\n`0` success, `1` user abort, `2` error\n\n## Examples\n\n```bash\n# TypeScript Worker\nnpm create cloudflare@latest my-api -- --type=hello-world --lang=ts --no-deploy\n\n# Next.js on Pages\nnpm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts\n\n# Astro blog\nnpm create cloudflare@latest my-blog -- --type=web-app --framework=astro --ts --deploy\n\n# CI: non-interactive\nnpm create cloudflare@latest my-app -- --type=web-app --framework=next --ts --no-git --no-deploy\n\n# GitHub template\nnpm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi\n\n# Convert existing project\nnpm create cloudflare@latest . -- --type=pre-existing --existing-script=./build/worker.js\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/c3/configuration.md", "content": "# C3 Generated Configuration\n\n## Output Structure\n\n```\nmy-app/\n├── src/index.ts # Worker entry point\n├── wrangler.jsonc # Cloudflare config\n├── package.json # Scripts\n├── tsconfig.json\n└── .gitignore\n```\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"$schema\": \"https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json\",\n \"name\": \"my-app\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2026-01-27\"\n}\n```\n\n## Binding Placeholders\n\nC3 generates **placeholder IDs** that must be replaced before deploy:\n\n```jsonc\n{\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"placeholder_kv_id\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_id\": \"00000000-...\" }]\n}\n```\n\n**Replace with real IDs:**\n```bash\nnpx wrangler kv namespace create MY_KV # Returns real ID\nnpx wrangler d1 create my-database # Returns real database_id\n```\n\n**Deployment error if not replaced:**\n```\nError: Invalid KV namespace ID \"placeholder_kv_id\"\n```\n\n## Scripts\n\n```json\n{\n \"scripts\": {\n \"dev\": \"wrangler dev\",\n \"deploy\": \"wrangler deploy\",\n \"cf-typegen\": \"wrangler types\"\n }\n}\n```\n\n## Type Generation\n\nRun after adding bindings:\n```bash\nnpm run cf-typegen\n```\n\nGenerates `.wrangler/types/runtime.d.ts`:\n```typescript\ninterface Env {\n MY_KV: KVNamespace;\n DB: D1Database;\n}\n```\n\n## Post-Creation Checklist\n\n1. Review `wrangler.jsonc` - check name, compatibility_date\n2. Replace placeholder binding IDs with real resource IDs\n3. Run `npm run cf-typegen`\n4. Test: `npm run dev`\n5. Deploy: `npm run deploy`\n6. Add secrets: `npx wrangler secret put SECRET_NAME`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/c3/gotchas.md", "content": "# C3 Troubleshooting\n\n## Deployment Issues\n\n### Placeholder IDs\n\n**Error:** \"Invalid namespace ID\" \n**Fix:** Replace placeholders in wrangler.jsonc with real IDs:\n```bash\nnpx wrangler kv namespace create MY_KV # Get real ID\n```\n\n### Authentication\n\n**Error:** \"Not authenticated\" \n**Fix:** `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`\n\n### Name Conflict\n\n**Error:** \"Worker already exists\" \n**Fix:** Change `name` in wrangler.jsonc\n\n## Platform Selection\n\n| Need | Platform |\n|------|----------|\n| Git integration, branch previews | `--platform=pages` |\n| Durable Objects, D1, Queues | Workers (default) |\n\nWrong platform? Recreate with correct `--platform` flag.\n\n## TypeScript Issues\n\n**\"Cannot find name 'KVNamespace'\"**\n```bash\nnpm run cf-typegen # Regenerate types\n# Restart TS server in editor\n```\n\n**Missing types after config change:** Re-run `npm run cf-typegen`\n\n## Package Manager\n\n**Multiple lockfiles causing issues:**\n```bash\nrm pnpm-lock.yaml # If using npm\nrm package-lock.json # If using pnpm\n```\n\n## CI/CD\n\n**CI hangs on prompts:**\n```bash\nnpm create cloudflare@latest my-app -- \\\n --type=hello-world --lang=ts --no-git --no-deploy\n```\n\n**Auth in CI:**\n```yaml\nenv:\n CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}\n```\n\n## Framework-Specific\n\n| Framework | Issue | Fix |\n|-----------|-------|-----|\n| Next.js | create-next-app failed | `npm cache clean --force`, retry |\n| Astro | Adapter missing | Install `@astrojs/cloudflare` |\n| Remix | Module errors | Update `@remix-run/cloudflare*` |\n\n## Compatibility Date\n\n**\"Feature X requires compatibility_date >= ...\"** \n**Fix:** Update `compatibility_date` in wrangler.jsonc to today's date\n\n## Node.js Version\n\n**\"Node.js version not supported\"** \n**Fix:** Install Node.js 18+ (`nvm install 20`)\n\n## Quick Reference\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| Invalid namespace ID | Placeholder binding | Create resource, update config |\n| Not authenticated | No login | `npx wrangler login` |\n| Cannot find KVNamespace | Missing types | `npm run cf-typegen` |\n| Worker already exists | Name conflict | Change `name` |\n| CI hangs | Missing flags | Add --type, --lang, --no-deploy |\n| Template not found | Bad name | Check cloudflare/templates |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/c3/patterns.md", "content": "# C3 Usage Patterns\n\n## Quick Workflows\n\n```bash\n# TypeScript API Worker\nnpm create cloudflare@latest my-api -- --type=hello-world --lang=ts --deploy\n\n# Next.js on Pages\nnpm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts --deploy\n\n# Astro static site \nnpm create cloudflare@latest my-blog -- --type=web-app --framework=astro --platform=pages --ts\n```\n\n## CI/CD (GitHub Actions)\n\n```yaml\n- name: Deploy\n run: npm run deploy\n env:\n CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}\n```\n\n**Non-interactive requires:**\n```bash\n--type= # Required\n--no-git # Recommended (CI already in git)\n--no-deploy # Deploy separately with secrets\n--framework= # For web-app\n--ts / --no-ts # Required\n```\n\n## Monorepo\n\nC3 detects workspace config (`package.json` workspaces or `pnpm-workspace.yaml`).\n\n```bash\ncd packages/\nnpm create cloudflare@latest my-worker -- --type=hello-world --lang=ts --no-deploy\n```\n\n## Custom Templates\n\n```bash\n# GitHub repo\nnpm create cloudflare@latest -- --template=username/repo\nnpm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi\n\n# Local path\nnpm create cloudflare@latest my-app -- --template=../my-template\n```\n\n**Template requires `c3.config.json`:**\n```json\n{\n \"name\": \"my-template\",\n \"category\": \"hello-world\",\n \"copies\": [{ \"path\": \"src/\" }, { \"path\": \"wrangler.jsonc\" }],\n \"transforms\": [{ \"path\": \"package.json\", \"jsonc\": { \"name\": \"{{projectName}}\" }}]\n}\n```\n\n## Existing Projects\n\n```bash\n# Add Cloudflare to existing Worker\nnpm create cloudflare@latest . -- --type=pre-existing --existing-script=./dist/index.js\n\n# Add to existing framework app\nnpm create cloudflare@latest . -- --type=web-app --framework=next --platform=pages --ts\n```\n\n## Post-Creation Checklist\n\n1. Review `wrangler.jsonc` - set `compatibility_date`, verify `name`\n2. Create bindings: `wrangler kv namespace create`, `wrangler d1 create`, `wrangler r2 bucket create`\n3. Generate types: `npm run cf-typegen`\n4. Test: `npm run dev`\n5. Deploy: `npm run deploy`\n6. Set secrets: `wrangler secret put SECRET_NAME`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cache-reserve/README.md", "content": "# Cloudflare Cache Reserve\n\n**Persistent cache storage built on R2 for long-term content retention**\n\n## Smart Shield Integration\n\nCache Reserve is part of **Smart Shield**, Cloudflare's comprehensive security and performance suite:\n\n- **Smart Shield Advanced tier**: Includes 2TB Cache Reserve storage\n- **Standalone purchase**: Available separately if not using Smart Shield\n- **Migration**: Existing standalone customers can migrate to Smart Shield bundles\n\n**Decision**: Already on Smart Shield Advanced? Cache Reserve is included. Otherwise evaluate standalone purchase vs Smart Shield upgrade.\n\n## Overview\n\nCache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.\n\n## Core Concepts\n\n### What is Cache Reserve?\n\n- **Persistent storage layer**: Built on R2, sits above tiered cache hierarchy\n- **Long-term retention**: 30-day default retention, extended on each access\n- **Automatic operation**: Works seamlessly with existing CDN, no code changes required\n- **Origin shielding**: Dramatically reduces origin egress by serving cached content longer\n- **Usage-based pricing**: Pay only for storage + read/write operations\n\n### Cache Hierarchy\n\n```\nVisitor Request\n ↓\nLower-Tier Cache (closest to visitor)\n ↓ (on miss)\nUpper-Tier Cache (closest to origin)\n ↓ (on miss)\nCache Reserve (R2 persistent storage)\n ↓ (on miss)\nOrigin Server\n```\n\n### How It Works\n\n1. **On cache miss**: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously\n2. **On edge eviction**: Content may be evicted from edge cache but remains in Cache Reserve\n3. **On subsequent request**: If edge cache misses but Cache Reserve hits → content restored to edge caches\n4. **Retention**: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)\n\n## When to Use Cache Reserve\n\n```\nNeed persistent caching?\n├─ High origin egress costs → Cache Reserve ✓\n├─ Long-tail content (archives, media libraries) → Cache Reserve ✓\n├─ Already using Smart Shield Advanced → Included! ✓\n├─ Video streaming with seeking (range requests) → ✗ Not supported\n├─ Dynamic/personalized content → ✗ Use edge cache only\n├─ Need per-request cache control from Workers → ✗ Use R2 directly\n└─ Frequently updated content (< 10hr lifetime) → ✗ Not eligible\n```\n\n## Asset Eligibility\n\nCache Reserve only stores assets meeting **ALL** criteria:\n\n- Cacheable per Cloudflare's standard rules\n- Minimum 10-hour TTL (36000 seconds)\n- `Content-Length` header present\n- Original files only (not transformed images)\n\n### Eligibility Checklist\n\nUse this checklist to verify if an asset is eligible:\n\n- [ ] Zone has Cache Reserve enabled\n- [ ] Zone has Tiered Cache enabled (required)\n- [ ] Asset TTL ≥ 10 hours (36,000 seconds)\n- [ ] `Content-Length` header present on origin response\n- [ ] No `Set-Cookie` header (or uses private directive)\n- [ ] `Vary` header is NOT `*` (can be `Accept-Encoding`)\n- [ ] Not an image transformation variant (original images OK)\n- [ ] Not a range request (no HTTP 206 support)\n- [ ] Not O2O (Orange-to-Orange) proxied request\n\n**All boxes must be checked for Cache Reserve eligibility.**\n\n### Not Eligible\n\n- Assets with TTL < 10 hours\n- Responses without `Content-Length` header\n- Image transformation variants (original images are eligible)\n- Responses with `Set-Cookie` headers\n- Responses with `Vary: *` header\n- Assets from R2 public buckets on same zone\n- O2O (Orange-to-Orange) setup requests\n- **Range requests** (video seeking, partial content downloads)\n\n## Quick Start\n\n```bash\n# Enable via Dashboard\nhttps://dash.cloudflare.com/caching/cache-reserve\n# Click \"Enable Storage Sync\" or \"Purchase\" button\n```\n\n**Prerequisites:**\n- Paid Cache Reserve plan or Smart Shield Advanced required\n- Tiered Cache required for optimal performance\n\n## Essential Commands\n\n```bash\n# Check Cache Reserve status\ncurl -X GET \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve\" \\\n -H \"Authorization: Bearer $API_TOKEN\"\n\n# Enable Cache Reserve\ncurl -X PATCH \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"value\": \"on\"}'\n\n# Check asset cache status\ncurl -I https://example.com/asset.jpg | grep -i cache\n```\n\n## In This Reference\n\n| Task | Files |\n|------|-------|\n| Evaluate if Cache Reserve fits your use case | README.md (this file) |\n| Enable Cache Reserve for your zone | README.md + [configuration.md](./configuration.md) |\n| Use with Workers (understand limitations) | [api.md](./api.md) |\n| Setup via SDKs or IaC (TypeScript, Python, Terraform) | [configuration.md](./configuration.md) |\n| Optimize costs and debug issues | [patterns.md](./patterns.md) + [gotchas.md](./gotchas.md) |\n| Understand eligibility and troubleshoot | [gotchas.md](./gotchas.md) → [patterns.md](./patterns.md) |\n\n**Files:**\n- [configuration.md](./configuration.md) - Setup, API, SDKs, and Cache Rules\n- [api.md](./api.md) - Purging, monitoring, Workers integration\n- [patterns.md](./patterns.md) - Best practices, cost optimization, debugging\n- [gotchas.md](./gotchas.md) - Common issues, limitations, troubleshooting\n\n## See Also\n- [r2](../r2/) - Cache Reserve built on R2 storage\n- [workers](../workers/) - Workers integration with Cache API\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cache-reserve/api.md", "content": "# Cache Reserve API\n\n## Workers Integration\n\n```\n┌────────────────────────────────────────────────────────────────┐\n│ CRITICAL: Workers Cache API ≠ Cache Reserve │\n│ │\n│ • Workers caches.default / cache.put() → edge cache ONLY │\n│ • Cache Reserve → zone-level setting, automatic, no per-req │\n│ • You CANNOT selectively write to Cache Reserve from Workers │\n│ • Cache Reserve works with standard fetch(), not cache.put() │\n└────────────────────────────────────────────────────────────────┘\n```\n\nCache Reserve is a **zone-level configuration**, not a per-request API. It works automatically when enabled for the zone:\n\n### Standard Fetch (Recommended)\n\n```typescript\n// Cache Reserve works automatically via standard fetch\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // Standard fetch uses Cache Reserve automatically\n return await fetch(request);\n }\n};\n```\n\n### Cache API Limitations\n\n**IMPORTANT**: `cache.put()` is **NOT compatible** with Cache Reserve or Tiered Cache.\n\n```typescript\n// ❌ WRONG: cache.put() bypasses Cache Reserve\nconst cache = caches.default;\nlet response = await cache.match(request);\nif (!response) {\n response = await fetch(request);\n await cache.put(request, response.clone()); // Bypasses Cache Reserve!\n}\n\n// ✅ CORRECT: Use standard fetch for Cache Reserve compatibility\nreturn await fetch(request);\n\n// ✅ CORRECT: Use Cache API only for custom cache namespaces\nconst customCache = await caches.open('my-custom-cache');\nlet response = await customCache.match(request);\nif (!response) {\n response = await fetch(request);\n await customCache.put(request, response.clone()); // Custom cache OK\n}\n```\n\n## Purging and Cache Management\n\n### Purge by URL (Instant)\n\n```typescript\n// Purge specific URL from Cache Reserve immediately\nconst purgeCacheReserveByURL = async (\n zoneId: string,\n apiToken: string,\n urls: string[]\n) => {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${apiToken}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ files: urls })\n }\n );\n return await response.json();\n};\n\n// Example usage\nawait purgeCacheReserveByURL('zone123', 'token456', [\n 'https://example.com/image.jpg',\n 'https://example.com/video.mp4'\n]);\n```\n\n### Purge by Tag/Host/Prefix (Revalidation)\n\n```typescript\n// Purge by cache tag - forces revalidation, not immediate removal\nawait fetch(\n `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({ tags: ['tag1', 'tag2'] })\n }\n);\n```\n\n**Purge behavior:**\n- **By URL**: Immediate removal from Cache Reserve + edge cache\n- **By tag/host/prefix**: Revalidation only, assets remain in storage (costs continue)\n\n### Clear All Cache Reserve Data\n\n```typescript\n// Requires Cache Reserve OFF first\nawait fetch(\n `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve_clear`,\n { method: 'POST', headers: { 'Authorization': `Bearer ${apiToken}` } }\n);\n\n// Check status: GET same endpoint returns { state: \"In-progress\" | \"Completed\" }\n```\n\n**Process**: Disable Cache Reserve → Call clear endpoint → Wait up to 24hr → Re-enable\n\n## Monitoring and Analytics\n\n### Dashboard Analytics\n\nNavigate to **Caching > Cache Reserve** to view:\n\n- **Egress Savings**: Total bytes served from Cache Reserve vs origin egress cost saved\n- **Requests Served**: Cache Reserve hits vs misses breakdown\n- **Storage Used**: Current GB stored in Cache Reserve (billed monthly)\n- **Operations**: Class A (writes) and Class B (reads) operation counts\n- **Cost Tracking**: Estimated monthly costs based on current usage\n\n### Logpush Integration\n\n```typescript\n// Logpush field: CacheReserveUsed (boolean) - filter for Cache Reserve hits\n// Query Cache Reserve hits in analytics\nconst logpushQuery = `\n SELECT \n ClientRequestHost, \n COUNT(*) as requests, \n SUM(EdgeResponseBytes) as bytes_served,\n COUNT(CASE WHEN CacheReserveUsed = true THEN 1 END) as cache_reserve_hits,\n COUNT(CASE WHEN CacheReserveUsed = false THEN 1 END) as cache_reserve_misses\n FROM http_requests \n WHERE Timestamp >= NOW() - INTERVAL '24 hours'\n GROUP BY ClientRequestHost \n ORDER BY requests DESC\n`;\n\n// Filter only Cache Reserve hits\nconst crHitsQuery = `\n SELECT ClientRequestHost, COUNT(*) as requests, SUM(EdgeResponseBytes) as bytes\n FROM http_requests \n WHERE CacheReserveUsed = true AND Timestamp >= NOW() - INTERVAL '7 days'\n GROUP BY ClientRequestHost \n ORDER BY bytes DESC\n`;\n```\n\n### GraphQL Analytics\n\n```graphql\nquery CacheReserveAnalytics($zoneTag: string, $since: string, $until: string) {\n viewer {\n zones(filter: { zoneTag: $zoneTag }) {\n httpRequests1dGroups(\n filter: { datetime_geq: $since, datetime_leq: $until }\n limit: 1000\n ) {\n dimensions { date }\n sum {\n cachedBytes\n cachedRequests\n bytes\n requests\n }\n }\n }\n }\n}\n```\n\n## Pricing\n\n```typescript\n// Storage: $0.015/GB-month | Class A (writes): $4.50/M | Class B (reads): $0.36/M\n// Cache miss: 1A + 1B | Cache hit: 1B | Assets >1GB: proportionally more ops\n```\n\n## See Also\n\n- [README](./README.md) - Overview and core concepts\n- [Configuration](./configuration.md) - Setup and Cache Rules\n- [Patterns](./patterns.md) - Best practices and optimization\n- [Gotchas](./gotchas.md) - Common issues and troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cache-reserve/configuration.md", "content": "# Cache Reserve Configuration\n\n## Dashboard Setup\n\n**Minimum steps to enable:**\n\n```bash\n# Navigate to dashboard\nhttps://dash.cloudflare.com/caching/cache-reserve\n\n# Click \"Enable Storage Sync\" or \"Purchase\" button\n```\n\n**Prerequisites:**\n- Paid Cache Reserve plan or Smart Shield Advanced required\n- Tiered Cache **required** for Cache Reserve to function optimally\n\n## API Configuration\n\n### REST API\n\n```bash\n# Enable\ncurl -X PATCH \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve\" \\\n -H \"Authorization: Bearer $API_TOKEN\" -H \"Content-Type: application/json\" \\\n -d '{\"value\": \"on\"}'\n\n# Check status\ncurl -X GET \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve\" \\\n -H \"Authorization: Bearer $API_TOKEN\"\n```\n\n### TypeScript SDK\n\n```bash\nnpm install cloudflare\n```\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({\n apiToken: process.env.CLOUDFLARE_API_TOKEN,\n});\n\n// Enable Cache Reserve\nawait client.cache.cacheReserve.edit({\n zone_id: 'abc123',\n value: 'on',\n});\n\n// Get Cache Reserve status\nconst status = await client.cache.cacheReserve.get({\n zone_id: 'abc123',\n});\nconsole.log(status.value); // 'on' or 'off'\n```\n\n### Python SDK\n\n```bash\npip install cloudflare\n```\n\n```python\nfrom cloudflare import Cloudflare\n\nclient = Cloudflare(api_token=os.environ.get(\"CLOUDFLARE_API_TOKEN\"))\n\n# Enable Cache Reserve\nclient.cache.cache_reserve.edit(\n zone_id=\"abc123\",\n value=\"on\"\n)\n\n# Get Cache Reserve status\nstatus = client.cache.cache_reserve.get(zone_id=\"abc123\")\nprint(status.value) # 'on' or 'off'\n```\n\n### Terraform\n\n```hcl\nterraform {\n required_providers {\n cloudflare = {\n source = \"cloudflare/cloudflare\"\n version = \"~> 4.0\"\n }\n }\n}\n\nprovider \"cloudflare\" {\n api_token = var.cloudflare_api_token\n}\n\nresource \"cloudflare_zone_cache_reserve\" \"example\" {\n zone_id = var.zone_id\n enabled = true\n}\n\n# Tiered Cache is required for Cache Reserve\nresource \"cloudflare_tiered_cache\" \"example\" {\n zone_id = var.zone_id\n cache_type = \"smart\"\n}\n```\n\n### Pulumi\n\n```typescript\nimport * as cloudflare from \"@pulumi/cloudflare\";\n\n// Enable Cache Reserve\nconst cacheReserve = new cloudflare.ZoneCacheReserve(\"example\", {\n zoneId: zoneId,\n enabled: true,\n});\n\n// Enable Tiered Cache (required)\nconst tieredCache = new cloudflare.TieredCache(\"example\", {\n zoneId: zoneId,\n cacheType: \"smart\",\n});\n```\n\n### Required API Token Permissions\n\n- `Zone Settings Read`\n- `Zone Settings Write`\n- `Zone Read`\n- `Zone Write`\n\n## Cache Rules Integration\n\nControl Cache Reserve eligibility via Cache Rules:\n\n```typescript\n// Enable for static assets\n{\n action: 'set_cache_settings',\n action_parameters: {\n cache_reserve: { eligible: true, minimum_file_ttl: 86400 },\n edge_ttl: { mode: 'override_origin', default: 86400 },\n cache: true\n },\n expression: '(http.request.uri.path matches \"\\\\.(jpg|png|webp|pdf|zip)$\")'\n}\n\n// Disable for APIs\n{\n action: 'set_cache_settings',\n action_parameters: { cache_reserve: { eligible: false } },\n expression: '(http.request.uri.path matches \"^/api/\")'\n}\n\n// Create via API: PUT to zones/{zone_id}/rulesets/phases/http_request_cache_settings/entrypoint\n```\n\n## Wrangler Integration\n\nCache Reserve works automatically with Workers deployed via Wrangler. No special wrangler.jsonc configuration needed - enable Cache Reserve via Dashboard or API for the zone.\n\n## See Also\n\n- [README](./README.md) - Overview and core concepts\n- [API Reference](./api.md) - Purging and monitoring APIs\n- [Patterns](./patterns.md) - Best practices and optimization\n- [Gotchas](./gotchas.md) - Common issues and troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cache-reserve/gotchas.md", "content": "# Cache Reserve Gotchas\n\n## Common Errors\n\n### \"Assets Not Being Cached in Cache Reserve\"\n\n**Cause:** Asset is not cacheable, TTL < 10 hours, Content-Length header missing, or blocking headers present (Set-Cookie, Vary: *) \n**Solution:** Ensure minimum TTL of 10+ hours (`Cache-Control: public, max-age=36000`), add Content-Length header, remove Set-Cookie header, and set `Vary: Accept-Encoding` (not *)\n\n### \"Range Requests Not Working\" (Video Seeking Fails)\n\n**Cause:** Cache Reserve does **NOT** support range requests (HTTP 206 Partial Content) \n**Solution:** Range requests bypass Cache Reserve entirely. For video streaming with seeking:\n- Use edge cache only (shorter TTLs)\n- Consider R2 with direct access for range-heavy workloads\n- Accept that seekable content won't benefit from Cache Reserve persistence\n\n### \"Origin Bandwidth Higher Than Expected\"\n\n**Cause:** Cache Reserve fetches **uncompressed** content from origin, even though it serves compressed to visitors \n**Solution:** \n- If origin charges by bandwidth, factor in uncompressed transfer costs\n- Cache Reserve compresses for visitors automatically (saves visitor bandwidth)\n- Compare: origin egress savings vs higher uncompressed fetch costs\n\n### \"Cloudflare Images Not Caching with Cache Reserve\"\n\n**Cause:** Cloudflare Images with `Vary: Accept` header (format negotiation) is incompatible with Cache Reserve \n**Solution:** \n- Cache Reserve silently skips images with Vary for format negotiation\n- Original images (non-transformed) may still be eligible\n- Use Cloudflare Images variants or edge cache for transformed images\n\n### \"High Class A Operations Costs\"\n\n**Cause:** Frequent cache misses, short TTLs, or frequent revalidation \n**Solution:** Increase TTL for stable content (24+ hours), enable Tiered Cache to reduce direct Cache Reserve misses, or use stale-while-revalidate\n\n### \"Purge Not Working as Expected\"\n\n**Cause:** Purge by tag only triggers revalidation but doesn't remove from Cache Reserve storage \n**Solution:** Use purge by URL for immediate removal, or disable Cache Reserve then clear all data for complete removal\n\n### \"O2O (Orange-to-Orange) Assets Not Caching\"\n\n**Cause:** Orange-to-Orange (proxied zone requesting another proxied zone on Cloudflare) bypasses Cache Reserve \n**Solution:** \n- **What is O2O**: Zone A (proxied) → Zone B (proxied), both on Cloudflare\n- **Detection**: Check `cf-cache-status` for `BYPASS` and review request path\n- **Workaround**: Use R2 or direct origin access instead of O2O proxy chains\n\n### \"Cache Reserve must be OFF before clearing data\"\n\n**Cause:** Attempting to clear Cache Reserve data while it's still enabled \n**Solution:** Disable Cache Reserve first, wait briefly for propagation (5s), then clear data (can take up to 24 hours)\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Minimum TTL | 10 hours (36000 seconds) | Assets with shorter TTL not eligible |\n| Default retention | 30 days (2592000 seconds) | Configurable |\n| Maximum file size | Same as R2 limits | No practical limit |\n| Purge/clear time | Up to 24 hours | Complete propagation time |\n| Plan requirement | Paid Cache Reserve or Smart Shield | Not available on free plans |\n| Content-Length header | Required | Must be present for eligibility |\n| Set-Cookie header | Blocks caching | Must not be present (or use private directive) |\n| Vary header | Cannot be * | Can use Vary: Accept-Encoding |\n| Image transformations | Variants not eligible | Original images only |\n| Range requests | NOT supported | HTTP 206 bypasses Cache Reserve |\n| Compression | Fetches uncompressed | Serves compressed to visitors |\n| Worker control | Zone-level only | Cannot control per-request |\n| O2O requests | Bypassed | Orange-to-Orange not eligible |\n\n## Additional Resources\n\n- **Official Docs**: https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/\n- **API Reference**: https://developers.cloudflare.com/api/resources/cache/subresources/cache_reserve/\n- **Cache Rules**: https://developers.cloudflare.com/cache/how-to/cache-rules/\n- **Workers Cache API**: https://developers.cloudflare.com/workers/runtime-apis/cache/\n- **R2 Documentation**: https://developers.cloudflare.com/r2/\n- **Smart Shield**: https://developers.cloudflare.com/smart-shield/\n- **Tiered Cache**: https://developers.cloudflare.com/cache/how-to/tiered-cache/\n\n## Troubleshooting Flowchart\n\nAsset not caching in Cache Reserve?\n\n```\n1. Is Cache Reserve enabled for zone?\n → No: Enable via Dashboard or API\n → Yes: Continue to step 2\n\n2. Is Tiered Cache enabled?\n → No: Enable Tiered Cache (required!)\n → Yes: Continue to step 3\n\n3. Does asset have TTL ≥ 10 hours?\n → No: Increase via Cache Rules (edge_ttl override)\n → Yes: Continue to step 4\n\n4. Is Content-Length header present?\n → No: Fix origin to include Content-Length\n → Yes: Continue to step 5\n\n5. Is Set-Cookie header present?\n → Yes: Remove Set-Cookie or scope appropriately\n → No: Continue to step 6\n\n6. Is Vary header set to *?\n → Yes: Change to specific value (e.g., Accept-Encoding)\n → No: Continue to step 7\n\n7. Is this a range request?\n → Yes: Range requests bypass Cache Reserve (not supported)\n → No: Continue to step 8\n\n8. Is this an O2O (Orange-to-Orange) request?\n → Yes: O2O bypasses Cache Reserve\n → No: Continue to step 9\n\n9. Check Logpush CacheReserveUsed field\n → Filter logs to see if assets ever hit Cache Reserve\n → Verify cf-cache-status header (should be HIT after first request)\n```\n\n## See Also\n\n- [README](./README.md) - Overview and core concepts\n- [Configuration](./configuration.md) - Setup and Cache Rules\n- [API Reference](./api.md) - Purging and monitoring\n- [Patterns](./patterns.md) - Best practices and optimization\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cache-reserve/patterns.md", "content": "# Cache Reserve Patterns\n\n## Best Practices\n\n### 1. Always Enable Tiered Cache\n\n```typescript\n// Cache Reserve is designed for use WITH Tiered Cache\nconst configuration = {\n tieredCache: 'enabled', // Required for optimal performance\n cacheReserve: 'enabled', // Works best with Tiered Cache\n \n hierarchy: [\n 'Lower-Tier Cache (visitor)',\n 'Upper-Tier Cache (origin region)',\n 'Cache Reserve (persistent)',\n 'Origin'\n ]\n};\n```\n\n### 2. Set Appropriate Cache-Control Headers\n\n```typescript\n// Origin response headers for Cache Reserve eligibility\nconst originHeaders = {\n 'Cache-Control': 'public, max-age=86400', // 24hr (minimum 10hr)\n 'Content-Length': '1024000', // Required\n 'Cache-Tag': 'images,product-123', // Optional: purging\n 'ETag': '\"abc123\"', // Optional: revalidation\n // Avoid: 'Set-Cookie' and 'Vary: *' prevent caching\n};\n```\n\n### 3. Use Cache Rules for Fine-Grained Control\n\n```typescript\n// Different TTLs for different content types\nconst cacheRules = [\n {\n description: 'Long-term cache for immutable assets',\n expression: '(http.request.uri.path matches \"^/static/.*\\\\.[a-f0-9]{8}\\\\.\")',\n action_parameters: {\n cache_reserve: { eligible: true },\n edge_ttl: { mode: 'override_origin', default: 2592000 }, // 30 days\n cache: true\n }\n },\n {\n description: 'Moderate cache for regular images',\n expression: '(http.request.uri.path matches \"\\\\.(jpg|png|webp)$\")',\n action_parameters: {\n cache_reserve: { eligible: true },\n edge_ttl: { mode: 'override_origin', default: 86400 }, // 24 hours\n cache: true\n }\n },\n {\n description: 'Exclude API from Cache Reserve',\n expression: '(http.request.uri.path matches \"^/api/\")',\n action_parameters: { cache_reserve: { eligible: false }, cache: false }\n }\n];\n```\n\n### 4. Making Assets Cache Reserve Eligible from Workers\n\n**Note**: This modifies response headers to meet eligibility criteria but does NOT directly control Cache Reserve storage (which is zone-level automatic).\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const response = await fetch(request);\n if (!response.ok) return response;\n \n const headers = new Headers(response.headers);\n headers.set('Cache-Control', 'public, max-age=36000'); // 10hr minimum\n headers.delete('Set-Cookie'); // Blocks caching\n \n // Ensure Content-Length present\n if (!headers.has('Content-Length')) {\n const blob = await response.blob();\n headers.set('Content-Length', blob.size.toString());\n return new Response(blob, { status: response.status, headers });\n }\n \n return new Response(response.body, { status: response.status, headers });\n }\n};\n```\n\n### 5. Hostname Best Practices\n\nUse Worker's hostname for efficient caching - avoid overriding hostname unnecessarily.\n\n## Architecture Patterns\n\n### Multi-Tier Caching + Immutable Assets\n\n```typescript\n// Optimal: L1 (visitor) → L2 (region) → L3 (Cache Reserve) → Origin\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n const isImmutable = /\\.[a-f0-9]{8,}\\.(js|css|jpg|png|woff2)$/.test(url.pathname);\n const response = await fetch(request);\n \n if (isImmutable) {\n const headers = new Headers(response.headers);\n headers.set('Cache-Control', 'public, max-age=31536000, immutable');\n return new Response(response.body, { status: response.status, headers });\n }\n return response;\n }\n};\n```\n\n## Cost Optimization\n\n### Cost Calculator\n\n```typescript\ninterface CacheReserveEstimate {\n avgAssetSizeGB: number;\n uniqueAssets: number;\n monthlyReads: number;\n monthlyWrites: number;\n originEgressCostPerGB: number; // e.g., AWS: $0.09/GB\n}\n\nfunction estimateMonthlyCost(input: CacheReserveEstimate) {\n // Cache Reserve pricing\n const storageCostPerGBMonth = 0.015;\n const classAPerMillion = 4.50; // writes\n const classBPerMillion = 0.36; // reads\n \n // Calculate Cache Reserve costs\n const totalStorageGB = input.avgAssetSizeGB * input.uniqueAssets;\n const storageCost = totalStorageGB * storageCostPerGBMonth;\n const writeCost = (input.monthlyWrites / 1_000_000) * classAPerMillion;\n const readCost = (input.monthlyReads / 1_000_000) * classBPerMillion;\n \n const cacheReserveCost = storageCost + writeCost + readCost;\n \n // Calculate origin egress cost (what you'd pay without Cache Reserve)\n const totalTrafficGB = (input.monthlyReads * input.avgAssetSizeGB);\n const originEgressCost = totalTrafficGB * input.originEgressCostPerGB;\n \n // Savings calculation\n const savings = originEgressCost - cacheReserveCost;\n const savingsPercent = ((savings / originEgressCost) * 100).toFixed(1);\n \n return {\n cacheReserveCost: `$${cacheReserveCost.toFixed(2)}`,\n originEgressCost: `$${originEgressCost.toFixed(2)}`,\n monthlySavings: `$${savings.toFixed(2)}`,\n savingsPercent: `${savingsPercent}%`,\n breakdown: {\n storage: `$${storageCost.toFixed(2)}`,\n writes: `$${writeCost.toFixed(2)}`,\n reads: `$${readCost.toFixed(2)}`,\n }\n };\n}\n\n// Example: Media library\nconst mediaLibrary = estimateMonthlyCost({\n avgAssetSizeGB: 0.005, // 5MB images\n uniqueAssets: 10_000,\n monthlyReads: 5_000_000,\n monthlyWrites: 50_000,\n originEgressCostPerGB: 0.09, // AWS S3\n});\n\nconsole.log(mediaLibrary);\n// {\n// cacheReserveCost: \"$9.98\",\n// originEgressCost: \"$25.00\",\n// monthlySavings: \"$15.02\",\n// savingsPercent: \"60.1%\",\n// breakdown: { storage: \"$0.75\", writes: \"$0.23\", reads: \"$9.00\" }\n// }\n```\n\n### Optimization Guidelines\n\n- **Set appropriate TTLs**: 10hr minimum, 24hr+ optimal for stable content, 30d max cautiously\n- **Cache high-value stable assets**: Images, media, fonts, archives, documentation\n- **Exclude frequently changing**: APIs, user-specific content, real-time data\n- **Compression note**: Cache Reserve fetches uncompressed from origin, serves compressed to visitors - factor in origin egress costs\n\n## See Also\n\n- [README](./README.md) - Overview and core concepts\n- [Configuration](./configuration.md) - Setup and Cache Rules\n- [API Reference](./api.md) - Purging and monitoring\n- [Gotchas](./gotchas.md) - Common issues and troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/containers/README.md", "content": "# Cloudflare Containers Skill Reference\n\n**APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers**\n\nUse when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patterns.\n\n## Beta Status\n\n⚠️ Containers is currently in **beta**. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.\n\n## Core Concepts\n\n**Container as Durable Object:** Each container is a Durable Object with persistent identity. Accessed via `getByName(id)` or `getRandom()`.\n\n**Image deployment:** Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).\n\n**Lifecycle:** cold start (2-3s) → running → `sleepAfter` timeout → stopped. No autoscaling - manual load balancing via `getRandom()`.\n\n**Persistent identity, ephemeral disk:** Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.\n\n## Quick Start\n\n```typescript\nimport { Container } from \"@cloudflare/containers\";\n\nexport class MyContainer extends Container {\n defaultPort = 8080;\n sleepAfter = \"30m\";\n}\n\nexport default {\n async fetch(request: Request, env: Env) {\n const container = env.MY_CONTAINER.getByName(\"instance-1\");\n await container.startAndWaitForPorts();\n return container.fetch(request);\n }\n};\n```\n\n## Reading Order\n\n| Task | Files |\n|------|-------|\n| Setup new container project | README → configuration.md |\n| Implement container logic | README → api.md → patterns.md |\n| Choose routing pattern | patterns.md (routing section) |\n| Debug issues | gotchas.md |\n| Production hardening | gotchas.md → patterns.md (lifecycle) |\n\n## Routing Decision Tree\n\n**How should requests reach containers?**\n\n- **Same user/session → same container:** Use `getByName(sessionId)` for session affinity\n- **Stateless, spread load:** Use `getRandom()` for load balancing\n- **Job per container:** Use `getByName(jobId)` + explicit lifecycle management\n- **Single global instance:** Use `getByName(\"singleton\")`\n\n## When to Use Containers vs Workers\n\n**Use Containers when:**\n- Need stateful, long-lived processes (sessions, WebSockets, games)\n- Running existing containerized apps (Node.js, Python, custom binaries)\n- Need filesystem access or specific system dependencies\n- Per-user/session isolation with dedicated compute\n\n**Use Workers when:**\n- Stateless HTTP handlers\n- Sub-millisecond cold starts required\n- Auto-scaling to zero critical\n- Simple request/response patterns\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Wrangler config, instance types, Container class properties, environment variables, account limits\n- **[api.md](api.md)** - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection\n- **[patterns.md](patterns.md)** - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration\n- **[gotchas.md](gotchas.md)** - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats\n\n## See Also\n\n- [Durable Objects](../durable-objects/) - Containers extend Durable Objects\n- [Workflows](../workflows/) - Orchestrate container operations\n- [Queues](../queues/) - Trigger containers from queue messages\n- [Cloudflare Docs](https://developers.cloudflare.com/containers/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/containers/api.md", "content": "## Container Class API\n\n```typescript\nimport { Container } from \"@cloudflare/containers\";\n\nexport class MyContainer extends Container {\n defaultPort = 8080;\n requiredPorts = [8080];\n sleepAfter = \"30m\";\n enableInternet = true;\n pingEndpoint = \"/health\";\n envVars = {};\n entrypoint = [];\n\n onStart() { /* container started */ }\n onStop() { /* container stopping */ }\n onError(error: Error) { /* container error */ }\n onActivityExpired(): boolean { /* timeout, return true to stay alive */ }\n async alarm() { /* scheduled task */ }\n}\n```\n\n## Routing\n\n**getByName(id)** - Named instance for session affinity, per-user state\n**getRandom()** - Random instance for load balancing stateless services\n\n```typescript\nconst container = env.MY_CONTAINER.getByName(\"user-123\");\nconst container = env.MY_CONTAINER.getRandom();\n```\n\n## Startup Methods\n\n### start() - Basic start (8s timeout)\n\n```typescript\nawait container.start();\nawait container.start({ envVars: { KEY: \"value\" } });\n```\n\nReturns when **process starts**, NOT when ports ready. Use for fire-and-forget.\n\n### startAndWaitForPorts() - Recommended (20s timeout)\n\n```typescript\nawait container.startAndWaitForPorts(); // Uses requiredPorts\nawait container.startAndWaitForPorts({ ports: [8080, 9090] });\nawait container.startAndWaitForPorts({ \n ports: [8080],\n startOptions: { envVars: { KEY: \"value\" } }\n});\n```\n\nReturns when **ports listening**. Use before HTTP/TCP requests.\n\n**Port resolution:** explicit ports → requiredPorts → defaultPort → port 33\n\n### waitForPort() - Wait for specific port\n\n```typescript\nawait container.waitForPort(8080);\nawait container.waitForPort(8080, { timeout: 30000 });\n```\n\n## Communication\n\n### fetch() - HTTP with WebSocket support\n\n```typescript\n// ✅ Supports WebSocket upgrades\nconst response = await container.fetch(request);\nconst response = await container.fetch(\"http://container/api\", {\n method: \"POST\",\n body: JSON.stringify({ data: \"value\" })\n});\n```\n\n**Use for:** All HTTP, especially WebSocket.\n\n### containerFetch() - HTTP only (no WebSocket)\n\n```typescript\n// ❌ No WebSocket support\nconst response = await container.containerFetch(request);\n```\n\n**⚠️ Critical:** Use `fetch()` for WebSocket, not `containerFetch()`.\n\n### TCP Connections\n\n```typescript\nconst port = this.ctx.container.getTcpPort(8080);\nconst conn = port.connect();\nawait conn.opened;\n\nif (request.body) await request.body.pipeTo(conn.writable);\nreturn new Response(conn.readable);\n```\n\n### switchPort() - Change default port\n\n```typescript\nthis.switchPort(8081); // Subsequent fetch() uses this port\n```\n\n## Lifecycle Hooks\n\n### onStart()\n\nCalled when container process starts (ports may not be ready). Runs in `blockConcurrencyWhile` - no concurrent requests.\n\n```typescript\nonStart() {\n console.log(\"Container starting\");\n}\n```\n\n### onStop()\n\nCalled when SIGTERM received. 15 minutes until SIGKILL. Use for graceful shutdown.\n\n```typescript\nonStop() {\n // Save state, close connections, flush logs\n}\n```\n\n### onError()\n\nCalled when container crashes or fails to start.\n\n```typescript\nonError(error: Error) {\n console.error(\"Container error:\", error);\n}\n```\n\n### onActivityExpired()\n\nCalled when `sleepAfter` timeout reached. Return `true` to stay alive, `false` to stop.\n\n```typescript\nonActivityExpired(): boolean {\n if (this.hasActiveConnections()) return true; // Keep alive\n return false; // OK to stop\n}\n```\n\n## Scheduling\n\n```typescript\nexport class ScheduledContainer extends Container {\n async fetch(request: Request) {\n await this.schedule(Date.now() + 60000); // 1 minute\n await this.schedule(\"2026-01-28T00:00:00Z\"); // ISO string\n return new Response(\"Scheduled\");\n }\n\n async alarm() {\n // Called when schedule fires (SQLite-backed, survives restarts)\n }\n}\n```\n\n**⚠️ Don't override `alarm()` directly when using `schedule()` helper.**\n\n## State Inspection\n\n### External state check\n\n```typescript\nconst state = await container.getState();\n// state.status: \"starting\" | \"running\" | \"stopping\" | \"stopped\"\n```\n\n### Internal state check\n\n```typescript\nexport class MyContainer extends Container {\n async fetch(request: Request) {\n if (this.ctx.container.running) { ... }\n }\n}\n```\n\n**⚠️ Use `getState()` for external checks, `ctx.container.running` for internal.**\n" }, { "path": "skills/.curated/cloudflare-deploy/references/containers/configuration.md", "content": "## Wrangler Configuration\n\n### Basic Container Config\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2026-01-10\",\n \"containers\": [\n {\n \"class_name\": \"MyContainer\",\n \"image\": \"./Dockerfile\", // Path to Dockerfile or directory with Dockerfile\n \"instance_type\": \"standard-1\", // Predefined or custom (see below)\n \"max_instances\": 10\n }\n ],\n \"durable_objects\": {\n \"bindings\": [\n {\n \"name\": \"MY_CONTAINER\",\n \"class_name\": \"MyContainer\"\n }\n ]\n },\n \"migrations\": [\n {\n \"tag\": \"v1\",\n \"new_sqlite_classes\": [\"MyContainer\"] // Must use new_sqlite_classes\n }\n ]\n}\n```\n\nKey config requirements:\n- `image` - Path to Dockerfile or directory containing Dockerfile\n- `class_name` - Must match Container class export name\n- `max_instances` - Max concurrent container instances\n- Must configure Durable Objects binding AND migrations\n\n### Instance Types\n\n#### Predefined Types\n\n| Type | vCPU | Memory | Disk |\n|------|------|--------|------|\n| lite | 1/16 | 256 MiB | 2 GB |\n| basic | 1/4 | 1 GiB | 4 GB |\n| standard-1 | 1/2 | 4 GiB | 8 GB |\n| standard-2 | 1 | 6 GiB | 12 GB |\n| standard-3 | 2 | 8 GiB | 16 GB |\n| standard-4 | 4 | 12 GiB | 20 GB |\n\n```jsonc\n{\n \"containers\": [\n {\n \"class_name\": \"MyContainer\",\n \"image\": \"./Dockerfile\",\n \"instance_type\": \"standard-2\" // Use predefined type\n }\n ]\n}\n```\n\n#### Custom Types (Jan 2026 Feature)\n\n```jsonc\n{\n \"containers\": [\n {\n \"class_name\": \"MyContainer\",\n \"image\": \"./Dockerfile\",\n \"instance_type_custom\": {\n \"vcpu\": 2, // 1-4 vCPU\n \"memory_mib\": 8192, // 512-12288 MiB (up to 12 GiB)\n \"disk_mib\": 16384 // 2048-20480 MiB (up to 20 GB)\n }\n }\n ]\n}\n```\n\n**Custom type constraints:**\n- Minimum 3 GiB memory per vCPU\n- Maximum 2 GB disk per 1 GiB memory\n- Max 4 vCPU, 12 GiB memory, 20 GB disk per container\n\n### Account Limits\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| Total memory (all containers) | 400 GiB | Across all running containers |\n| Total vCPU (all containers) | 100 | Across all running containers |\n| Total disk (all containers) | 2 TB | Across all running containers |\n| Image storage per account | 50 GB | Stored container images |\n\n### Container Class Properties\n\n```typescript\nimport { Container } from \"@cloudflare/containers\";\n\nexport class MyContainer extends Container {\n // Port Configuration\n defaultPort = 8080; // Default port for fetch() calls\n requiredPorts = [8080, 9090]; // Ports to wait for in startAndWaitForPorts()\n\n // Lifecycle\n sleepAfter = \"30m\"; // Inactivity timeout (5m, 30m, 2h, etc.)\n\n // Network\n enableInternet = true; // Allow outbound internet access\n\n // Health Check\n pingEndpoint = \"/health\"; // Health check endpoint path\n\n // Environment\n envVars = { // Environment variables passed to container\n NODE_ENV: \"production\",\n LOG_LEVEL: \"info\"\n };\n\n // Startup\n entrypoint = [\"/bin/start.sh\"]; // Override image entrypoint (optional)\n}\n```\n\n**Property details:**\n\n- **`defaultPort`**: Port used when calling `container.fetch()` without explicit port. Falls back to port 33 if not set.\n\n- **`requiredPorts`**: Array of ports that must be listening before `startAndWaitForPorts()` returns. First port becomes default if `defaultPort` not set.\n\n- **`sleepAfter`**: Duration string (e.g., \"5m\", \"30m\", \"2h\"). Container stops after this period of inactivity. Timer resets on each request.\n\n- **`enableInternet`**: Boolean. If `true`, container can make outbound HTTP/TCP requests.\n\n- **`pingEndpoint`**: Path used for health checks. Should respond with 2xx status.\n\n- **`envVars`**: Object of environment variables. Merged with runtime-provided vars (see below).\n\n- **`entrypoint`**: Array of strings. Overrides container image's CMD/ENTRYPOINT.\n\n### Runtime Environment Variables\n\nCloudflare automatically provides these environment variables to containers:\n\n| Variable | Description |\n|----------|-------------|\n| `CLOUDFLARE_APPLICATION_ID` | Worker application ID |\n| `CLOUDFLARE_COUNTRY_A2` | Two-letter country code of request origin |\n| `CLOUDFLARE_LOCATION` | Cloudflare data center location |\n| `CLOUDFLARE_REGION` | Region identifier |\n| `CLOUDFLARE_DURABLE_OBJECT_ID` | Container's Durable Object ID |\n\nCustom `envVars` from Container class are merged with these. Custom vars override runtime vars if names conflict.\n\n### Image Management\n\n**Distribution model:** Images pre-fetched to all global locations before deployment. Ensures fast cold starts (2-3s typical).\n\n**Rolling deploys:** Unlike Workers (instant), container deployments roll out gradually. Old versions continue running during rollout.\n\n**Ephemeral disk:** Container disk is ephemeral and resets on each stop. Use Durable Object storage (`this.ctx.storage`) for persistence.\n\n## wrangler.toml Format\n\n```toml\nname = \"my-worker\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2026-01-10\"\n\n[[containers]]\nclass_name = \"MyContainer\"\nimage = \"./Dockerfile\"\ninstance_type = \"standard-2\"\nmax_instances = 10\n\n[[durable_objects.bindings]]\nname = \"MY_CONTAINER\"\nclass_name = \"MyContainer\"\n\n[[migrations]]\ntag = \"v1\"\nnew_sqlite_classes = [\"MyContainer\"]\n```\n\nBoth `wrangler.jsonc` and `wrangler.toml` are supported. Use `wrangler.jsonc` for comments and better IDE support.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/containers/gotchas.md", "content": "## Critical Gotchas\n\n### ⚠️ WebSocket: fetch() vs containerFetch()\n\n**Problem:** WebSocket connections fail silently\n\n**Cause:** `containerFetch()` doesn't support WebSocket upgrades\n\n**Fix:** Always use `fetch()` for WebSocket\n\n```typescript\n// ❌ WRONG\nreturn container.containerFetch(request);\n\n// ✅ CORRECT\nreturn container.fetch(request);\n```\n\n### ⚠️ startAndWaitForPorts() vs start()\n\n**Problem:** \"connection refused\" after `start()`\n\n**Cause:** `start()` returns when process starts, NOT when ports ready\n\n**Fix:** Use `startAndWaitForPorts()` before requests\n\n```typescript\n// ❌ WRONG\nawait container.start();\nreturn container.fetch(request);\n\n// ✅ CORRECT\nawait container.startAndWaitForPorts();\nreturn container.fetch(request);\n```\n\n### ⚠️ Activity Timeout on Long Operations\n\n**Problem:** Container stops during long work\n\n**Cause:** `sleepAfter` based on request activity, not internal work\n\n**Fix:** Renew timeout by touching storage\n\n```typescript\nconst interval = setInterval(() => {\n this.ctx.storage.put(\"keepalive\", Date.now());\n}, 60000);\n\ntry {\n await this.doLongWork(data);\n} finally {\n clearInterval(interval);\n}\n```\n\n### ⚠️ blockConcurrencyWhile for Startup\n\n**Problem:** Race conditions during initialization\n\n**Fix:** Use `blockConcurrencyWhile` for atomic initialization\n\n```typescript\nawait this.ctx.blockConcurrencyWhile(async () => {\n if (!this.initialized) {\n await this.startAndWaitForPorts();\n this.initialized = true;\n }\n});\n```\n\n### ⚠️ Lifecycle Hooks Block Requests\n\n**Problem:** Container unresponsive during `onStart()`\n\n**Cause:** Hooks run in `blockConcurrencyWhile` - no concurrent requests\n\n**Fix:** Keep hooks fast, avoid long operations\n\n### ⚠️ Don't Override alarm() When Using schedule()\n\n**Problem:** Scheduled tasks don't execute\n\n**Cause:** `schedule()` uses `alarm()` internally\n\n**Fix:** Implement `alarm()` to handle scheduled tasks\n\n## Common Errors\n\n### \"Container start timeout\"\n\n**Cause:** Container took >8s (`start()`) or >20s (`startAndWaitForPorts()`)\n\n**Solutions:**\n- Optimize image (smaller base, fewer layers)\n- Check `entrypoint` correct\n- Verify app listens on correct ports\n- Increase timeout if needed\n\n### \"Port not available\"\n\n**Cause:** Calling `fetch()` before port ready\n\n**Solution:** Use `startAndWaitForPorts()`\n\n### \"Container memory exceeded\"\n\n**Cause:** Using more memory than instance type allows\n\n**Solutions:**\n- Use larger instance type (standard-2, standard-3, standard-4)\n- Optimize app memory usage\n- Use custom instance type\n\n```jsonc\n\"instance_type_custom\": {\n \"vcpu\": 2,\n \"memory_mib\": 8192\n}\n```\n\n### \"Max instances reached\"\n\n**Cause:** All `max_instances` slots in use\n\n**Solutions:**\n- Increase `max_instances`\n- Implement proper `sleepAfter`\n- Use `getRandom()` for distribution\n- Check for instance leaks\n\n### \"No container instance available\"\n\n**Cause:** Account capacity limits reached\n\n**Solutions:**\n- Check account limits\n- Review instance types across containers\n- Contact Cloudflare support\n\n## Limits\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| Cold start | 2-3s | Image pre-fetched globally |\n| Graceful shutdown | 15 min | SIGTERM → SIGKILL |\n| `start()` timeout | 8s | Process start |\n| `startAndWaitForPorts()` timeout | 20s | Port ready |\n| Max vCPU per container | 4 | standard-4 or custom |\n| Max memory per container | 12 GiB | standard-4 or custom |\n| Max disk per container | 20 GB | Ephemeral, resets |\n| Account total memory | 400 GiB | All containers |\n| Account total vCPU | 100 | All containers |\n| Account total disk | 2 TB | All containers |\n| Image storage | 50 GB | Per account |\n| Disk persistence | None | Use DO storage |\n\n## Best Practices\n\n1. **Use `startAndWaitForPorts()` by default** - Prevents port errors\n2. **Set appropriate `sleepAfter`** - Balance resources vs cold starts\n3. **Use `fetch()` for WebSocket** - Not `containerFetch()`\n4. **Design for restarts** - Ephemeral disk, implement graceful shutdown\n5. **Monitor resources** - Stay within account limits\n6. **Keep hooks fast** - Run in `blockConcurrencyWhile`\n7. **Renew activity for long ops** - Touch storage to prevent timeout\n\n## Beta Caveats\n\n⚠️ Containers in **beta**:\n\n- **API may change** without notice\n- **No SLA** guarantees\n- **Limited regions** initially\n- **No autoscaling** - manual via `getRandom()`\n- **Rolling deploys** only (not instant like Workers)\n\nPlan for API changes, test thoroughly before production.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/containers/patterns.md", "content": "## Routing Patterns\n\n### Session Affinity (Stateful)\n\n```typescript\nexport class SessionBackend extends Container {\n defaultPort = 3000;\n sleepAfter = \"30m\";\n}\n\nexport default {\n async fetch(request: Request, env: Env) {\n const sessionId = request.headers.get(\"X-Session-ID\") || crypto.randomUUID();\n const container = env.SESSION_BACKEND.getByName(sessionId);\n await container.startAndWaitForPorts();\n return container.fetch(request);\n }\n};\n```\n\n**Use:** User sessions, WebSocket, stateful games, per-user caching.\n\n### Load Balancing (Stateless)\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env) {\n const container = env.STATELESS_API.getRandom();\n await container.startAndWaitForPorts();\n return container.fetch(request);\n }\n};\n```\n\n**Use:** Stateless HTTP APIs, CPU-intensive work, read-only queries.\n\n### Singleton Pattern\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env) {\n const container = env.GLOBAL_SERVICE.getByName(\"singleton\");\n await container.startAndWaitForPorts();\n return container.fetch(request);\n }\n};\n```\n\n**Use:** Global cache, centralized coordinator, single source of truth.\n\n## WebSocket Forwarding\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env) {\n if (request.headers.get(\"Upgrade\") === \"websocket\") {\n const sessionId = request.headers.get(\"X-Session-ID\") || crypto.randomUUID();\n const container = env.WS_BACKEND.getByName(sessionId);\n await container.startAndWaitForPorts();\n \n // ⚠️ MUST use fetch(), not containerFetch()\n return container.fetch(request);\n }\n return new Response(\"Not a WebSocket request\", { status: 400 });\n }\n};\n```\n\n**⚠️ Critical:** Always use `fetch()` for WebSocket.\n\n## Graceful Shutdown\n\n```typescript\nexport class GracefulContainer extends Container {\n private connections = new Set();\n\n onStop() {\n // SIGTERM received, 15 minutes until SIGKILL\n for (const ws of this.connections) {\n ws.close(1001, \"Server shutting down\");\n }\n this.ctx.storage.put(\"shutdown-time\", Date.now());\n }\n\n onActivityExpired(): boolean {\n return this.connections.size > 0; // Keep alive if connections\n }\n}\n```\n\n## Concurrent Request Handling\n\n```typescript\nexport class SafeContainer extends Container {\n private initialized = false;\n\n async fetch(request: Request) {\n await this.ctx.blockConcurrencyWhile(async () => {\n if (!this.initialized) {\n await this.startAndWaitForPorts();\n this.initialized = true;\n }\n });\n return super.fetch(request);\n }\n}\n```\n\n**Use:** One-time initialization, preventing concurrent startup.\n\n## Activity Timeout Renewal\n\n```typescript\nexport class LongRunningContainer extends Container {\n sleepAfter = \"5m\";\n\n async processLongJob(data: unknown) {\n const interval = setInterval(() => {\n this.ctx.storage.put(\"keepalive\", Date.now());\n }, 60000);\n\n try {\n await this.doLongWork(data);\n } finally {\n clearInterval(interval);\n }\n }\n}\n```\n\n**Use:** Long operations exceeding `sleepAfter`.\n\n## Multiple Port Routing\n\n```typescript\nexport class MultiPortContainer extends Container {\n requiredPorts = [8080, 8081, 9090];\n\n async fetch(request: Request) {\n const path = new URL(request.url).pathname;\n if (path.startsWith(\"/grpc\")) this.switchPort(8081);\n else if (path.startsWith(\"/metrics\")) this.switchPort(9090);\n return super.fetch(request);\n }\n}\n```\n\n**Use:** Multi-protocol services (HTTP + gRPC), separate metrics endpoints.\n\n## Workflow Integration\n\n```typescript\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\n\nexport class ProcessingWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n const container = this.env.PROCESSOR.getByName(event.payload.jobId);\n \n await step.do(\"start\", async () => {\n await container.startAndWaitForPorts();\n });\n \n const result = await step.do(\"process\", async () => {\n return container.fetch(\"/process\", {\n method: \"POST\",\n body: JSON.stringify(event.payload.data)\n }).then(r => r.json());\n });\n \n return result;\n }\n}\n```\n\n**Use:** Orchestrating multi-step container operations, durable execution.\n\n## Queue Consumer Integration\n\n```typescript\nexport default {\n async queue(batch, env) {\n for (const msg of batch.messages) {\n try {\n const container = env.PROCESSOR.getByName(msg.body.jobId);\n await container.startAndWaitForPorts();\n \n const response = await container.fetch(\"/process\", {\n method: \"POST\",\n body: JSON.stringify(msg.body)\n });\n \n response.ok ? msg.ack() : msg.retry();\n } catch (err) {\n console.error(\"Queue processing error:\", err);\n msg.retry();\n }\n }\n }\n};\n```\n\n**Use:** Asynchronous job processing, batch operations, event-driven execution.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cron-triggers/README.md", "content": "# Cloudflare Cron Triggers\n\nSchedule Workers execution using cron expressions. Runs on Cloudflare's global network during underutilized periods.\n\n## Key Features\n\n- **UTC-only execution** - All schedules run on UTC time\n- **5-field cron syntax** - Quartz scheduler extensions (L, W, #)\n- **Global propagation** - 15min deployment delay\n- **At-least-once delivery** - Rare duplicate executions possible\n- **Workflow integration** - Trigger long-running multi-step tasks\n- **Green Compute** - Optional carbon-aware scheduling during low-carbon periods\n\n## Cron Syntax\n\n```\n ┌─────────── minute (0-59)\n │ ┌───────── hour (0-23)\n │ │ ┌─────── day of month (1-31)\n │ │ │ ┌───── month (1-12, JAN-DEC)\n │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday)\n * * * * *\n```\n\n**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)\n\n## Common Schedules\n\n```bash\n*/5 * * * * # Every 5 minutes\n0 * * * * # Hourly\n0 2 * * * # Daily 2am UTC (off-peak)\n0 9 * * MON-FRI # Weekdays 9am UTC\n0 0 1 * * # Monthly 1st midnight UTC\n0 9 L * * # Last day of month 9am UTC\n0 10 * * MON#2 # 2nd Monday 10am UTC\n*/10 9-17 * * MON-FRI # Every 10min, 9am-5pm weekdays\n```\n\n## Quick Start\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"name\": \"my-cron-worker\",\n \"triggers\": {\n \"crons\": [\"*/5 * * * *\", \"0 2 * * *\"]\n }\n}\n```\n\n**Handler:**\n```typescript\nexport default {\n async scheduled(\n controller: ScheduledController,\n env: Env,\n ctx: ExecutionContext,\n ): Promise {\n console.log(\"Cron:\", controller.cron);\n console.log(\"Time:\", new Date(controller.scheduledTime));\n \n ctx.waitUntil(asyncTask(env)); // Non-blocking\n },\n};\n```\n\n**Test locally:**\n```bash\nnpx wrangler dev\ncurl \"http://localhost:8787/__scheduled?cron=*/5+*+*+*+*\"\n```\n\n## Limits\n\n- **Free:** 3 triggers/worker, 10ms CPU\n- **Paid:** Unlimited triggers, 50ms CPU\n- **Propagation:** 15min global deployment\n- **Timezone:** UTC only\n\n## Reading Order\n\n**New to cron triggers?** Start here:\n1. This README - Overview and quick start\n2. [configuration.md](./configuration.md) - Set up your first cron trigger\n3. [api.md](./api.md) - Understand the handler API\n4. [patterns.md](./patterns.md) - Common use cases and examples\n\n**Troubleshooting?** Jump to [gotchas.md](./gotchas.md)\n\n## In This Reference\n- [configuration.md](./configuration.md) - wrangler config, env-specific schedules, Green Compute\n- [api.md](./api.md) - ScheduledController, noRetry(), waitUntil, testing patterns\n- [patterns.md](./patterns.md) - Use cases, monitoring, queue integration, Durable Objects\n- [gotchas.md](./gotchas.md) - Timezone issues, idempotency, security, testing\n\n## See Also\n- [workflows](../workflows/) - Alternative for long-running scheduled tasks\n- [workers](../workers/) - Worker runtime documentation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cron-triggers/api.md", "content": "# Cron Triggers API\n\n## Basic Handler\n\n```typescript\nexport default {\n async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise {\n console.log(\"Cron executed:\", new Date(controller.scheduledTime));\n },\n};\n```\n\n**JavaScript:** Same signature without types \n**Python:** `class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx)`\n\n## ScheduledController\n\n```typescript\ninterface ScheduledController {\n scheduledTime: number; // Unix ms when scheduled to run\n cron: string; // Expression that triggered (e.g., \"*/5 * * * *\")\n type: string; // Always \"scheduled\"\n noRetry(): void; // Prevent automatic retry on failure\n}\n```\n\n**Prevent retry on failure:**\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n try {\n await riskyOperation(env);\n } catch (error) {\n // Don't retry - failure is expected/acceptable\n controller.noRetry();\n console.error(\"Operation failed, not retrying:\", error);\n }\n },\n};\n```\n\n**When to use noRetry():**\n- External API failures outside your control (avoid hammering failed services)\n- Rate limit errors (retry would fail again immediately)\n- Duplicate execution detected (idempotency check failed)\n- Non-critical operations where skip is acceptable (analytics, caching)\n- Validation errors that won't resolve on retry\n\n## Handler Parameters\n\n**`controller: ScheduledController`**\n- Access cron expression and scheduled time\n\n**`env: Env`**\n- All bindings: KV, R2, D1, secrets, service bindings\n\n**`ctx: ExecutionContext`**\n- `ctx.waitUntil(promise)` - Extend execution for async tasks (logging, cleanup, external APIs)\n- First `waitUntil` failure recorded in Cron Events\n\n## Multiple Schedules\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n switch (controller.cron) {\n case \"*/3 * * * *\": ctx.waitUntil(updateRecentData(env)); break;\n case \"0 * * * *\": ctx.waitUntil(processHourlyAggregation(env)); break;\n case \"0 2 * * *\": ctx.waitUntil(performDailyMaintenance(env)); break;\n default: console.warn(`Unhandled: ${controller.cron}`);\n }\n },\n};\n```\n\n## ctx.waitUntil Usage\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const data = await fetchCriticalData(); // Critical path\n \n // Non-blocking background tasks\n ctx.waitUntil(Promise.all([\n logToAnalytics(data),\n cleanupOldRecords(env.DB),\n notifyWebhook(env.WEBHOOK_URL, data),\n ]));\n },\n};\n```\n\n## Workflow Integration\n\n```typescript\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\n\nexport class DataProcessingWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n const data = await step.do(\"fetch-data\", () => fetchLargeDataset());\n const processed = await step.do(\"process-data\", () => processDataset(data));\n await step.do(\"store-results\", () => storeResults(processed));\n }\n}\n\nexport default {\n async scheduled(controller, env, ctx) {\n const instance = await env.MY_WORKFLOW.create({\n params: { scheduledTime: controller.scheduledTime, cron: controller.cron },\n });\n console.log(`Started workflow: ${instance.id}`);\n },\n};\n```\n\n## Testing Handler\n\n**Local development (/__scheduled endpoint):**\n```bash\n# Start dev server\nnpx wrangler dev\n\n# Trigger any cron\ncurl \"http://localhost:8787/__scheduled?cron=*/5+*+*+*+*\"\n\n# Trigger specific cron with custom time\ncurl \"http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000\"\n```\n\n**Query parameters:**\n- `cron` - Required. URL-encoded cron expression (use `+` for spaces)\n- `scheduledTime` - Optional. Unix timestamp in milliseconds (defaults to current time)\n\n**Production security:** The `/__scheduled` endpoint is available in production and can be triggered by anyone. Block it or implement authentication - see [gotchas.md](./gotchas.md#security-concerns)\n\n**Unit testing (Vitest):**\n```typescript\n// test/scheduled.test.ts\nimport { describe, it, expect } from \"vitest\";\nimport { env } from \"cloudflare:test\";\nimport worker from \"../src/index\";\n\ndescribe(\"Scheduled Handler\", () => {\n it(\"processes scheduled event\", async () => {\n const controller = { scheduledTime: Date.now(), cron: \"*/5 * * * *\", type: \"scheduled\" as const, noRetry: () => {} };\n const ctx = { waitUntil: (p: Promise) => p, passThroughOnException: () => {} };\n await worker.scheduled(controller, env, ctx);\n expect(await env.MY_KV.get(\"last_run\")).toBeDefined();\n });\n \n it(\"handles multiple crons\", async () => {\n const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };\n await worker.scheduled({ scheduledTime: Date.now(), cron: \"*/5 * * * *\", type: \"scheduled\", noRetry: () => {} }, env, ctx);\n expect(await env.MY_KV.get(\"last_type\")).toBe(\"frequent\");\n });\n});\n```\n\n## Error Handling\n\n**Automatic retries:**\n- Failed cron executions are retried automatically unless `noRetry()` is called\n- Retry happens after a delay (typically minutes)\n- Only first `waitUntil()` failure is recorded in Cron Events\n\n**Best practices:**\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n try {\n await criticalOperation(env);\n } catch (error) {\n // Log error details\n console.error(\"Cron failed:\", {\n cron: controller.cron,\n scheduledTime: controller.scheduledTime,\n error: error.message,\n stack: error.stack,\n });\n \n // Decide: retry or skip\n if (error.message.includes(\"rate limit\")) {\n controller.noRetry(); // Skip retry for rate limits\n }\n // Otherwise allow automatic retry\n throw error;\n }\n },\n};\n```\n\n## See Also\n\n- [README.md](./README.md) - Overview\n- [patterns.md](./patterns.md) - Use cases, examples\n- [gotchas.md](./gotchas.md) - Common errors, testing issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cron-triggers/configuration.md", "content": "# Cron Triggers Configuration\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"name\": \"my-cron-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \n \"triggers\": {\n \"crons\": [\n \"*/5 * * * *\", // Every 5 minutes\n \"0 */2 * * *\", // Every 2 hours\n \"0 9 * * MON-FRI\", // Weekdays at 9am UTC\n \"0 2 1 * *\" // Monthly on 1st at 2am UTC\n ]\n }\n}\n```\n\n## Green Compute (Beta)\n\nSchedule crons during low-carbon periods for carbon-aware execution:\n\n```jsonc\n{\n \"name\": \"eco-cron-worker\",\n \"triggers\": {\n \"crons\": [\"0 2 * * *\"]\n },\n \"placement\": {\n \"mode\": \"smart\" // Runs during low-carbon periods\n }\n}\n```\n\n**Modes:**\n- `\"smart\"` - Carbon-aware scheduling (may delay up to 24h for optimal window)\n- Default (no placement config) - Standard scheduling (no delay)\n\n**How it works:**\n- Cloudflare delays execution until grid carbon intensity is lower\n- Maximum delay: 24 hours from scheduled time\n- Ideal for batch jobs with flexible timing requirements\n\n**Use cases:** \n- Nightly data processing and ETL pipelines\n- Weekly/monthly report generation\n- Database backups and maintenance\n- Analytics aggregation\n- ML model training\n\n**Not suitable for:** \n- Time-sensitive operations (SLA requirements)\n- User-facing features requiring immediate execution\n- Real-time monitoring and alerting\n- Compliance tasks with strict time windows\n\n## Environment-Specific Schedules\n\n```jsonc\n{\n \"name\": \"my-cron-worker\",\n \"triggers\": {\n \"crons\": [\"0 */6 * * *\"] // Prod: every 6 hours\n },\n \"env\": {\n \"staging\": {\n \"triggers\": {\n \"crons\": [\"*/15 * * * *\"] // Staging: every 15min\n }\n },\n \"dev\": {\n \"triggers\": {\n \"crons\": [\"*/5 * * * *\"] // Dev: every 5min\n }\n }\n }\n}\n```\n\n## Schedule Format\n\n**Structure:** `minute hour day-of-month month day-of-week`\n\n**Special chars:** `*` (any), `,` (list), `-` (range), `/` (step), `L` (last), `W` (weekday), `#` (nth)\n\n## Managing Triggers\n\n**Remove all:** `\"triggers\": { \"crons\": [] }` \n**Preserve existing:** Omit `\"triggers\"` field entirely\n\n## Deployment\n\n```bash\n# Deploy with config crons\nnpx wrangler deploy\n\n# Deploy specific environment\nnpx wrangler deploy --env production\n\n# View deployments\nnpx wrangler deployments list\n```\n\n**⚠️ Changes take up to 15 minutes to propagate globally**\n\n## API Management\n\n**Get triggers:**\n```bash\ncurl \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules\" \\\n -H \"Authorization: Bearer {api_token}\"\n```\n\n**Update triggers:**\n```bash\ncurl -X PUT \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules\" \\\n -H \"Authorization: Bearer {api_token}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"crons\": [\"*/5 * * * *\", \"0 2 * * *\"]}'\n```\n\n**Delete all:**\n```bash\ncurl -X PUT \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules\" \\\n -H \"Authorization: Bearer {api_token}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"crons\": []}'\n```\n\n## Combining Multiple Workers\n\nFor complex schedules, use multiple workers:\n\n```jsonc\n// worker-frequent.jsonc\n{\n \"name\": \"data-sync-frequent\",\n \"triggers\": { \"crons\": [\"*/5 * * * *\"] }\n}\n\n// worker-daily.jsonc\n{\n \"name\": \"reports-daily\",\n \"triggers\": { \"crons\": [\"0 2 * * *\"] },\n \"placement\": { \"mode\": \"smart\" }\n}\n\n// worker-weekly.jsonc\n{\n \"name\": \"cleanup-weekly\",\n \"triggers\": { \"crons\": [\"0 3 * * SUN\"] }\n}\n```\n\n**Benefits:**\n- Separate CPU limits per worker\n- Independent error isolation\n- Different Green Compute policies\n- Easier to maintain and debug\n\n## Validation\n\n**Test cron syntax:**\n- [crontab.guru](https://crontab.guru/) - Interactive validator\n- Wrangler validates on deploy but won't catch logic errors\n\n**Common mistakes:**\n- `0 0 * * *` runs daily at midnight UTC, not your local timezone\n- `*/60 * * * *` is invalid (use `0 * * * *` for hourly)\n- `0 2 31 * *` only runs on months with 31 days\n\n## See Also\n\n- [README.md](./README.md) - Overview, quick start\n- [api.md](./api.md) - Handler implementation\n- [patterns.md](./patterns.md) - Multi-cron routing examples\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cron-triggers/gotchas.md", "content": "# Cron Triggers Gotchas\n\n## Common Errors\n\n### \"Timezone Issues\"\n\n**Problem:** Cron runs at wrong time relative to local timezone \n**Cause:** All crons execute in UTC, no local timezone support \n**Solution:** Convert local time to UTC manually\n\n**Conversion formula:** `utcHour = (localHour - utcOffset + 24) % 24`\n\n**Examples:**\n- 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *`\n- 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *`\n- 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *`\n\n**Daylight Saving Time:** Adjust manually when DST changes, or schedule at times unaffected by DST (e.g., 2am-4am local time usually safe)\n\n### \"Cron Not Executing\"\n\n**Cause:** Missing `scheduled()` export, invalid syntax, propagation delay (<15min), or plan limits \n**Solution:** Verify export exists, validate at crontab.guru, wait 15+ min after deploy, check plan limits\n\n### \"Duplicate Executions\"\n\n**Cause:** At-least-once delivery \n**Solution:** Track execution IDs in KV - see idempotency pattern below\n\n### \"Execution Failures\"\n\n**Cause:** CPU exceeded, unhandled exceptions, network timeouts, binding errors \n**Solution:** Use try-catch, AbortController timeouts, `ctx.waitUntil()` for long ops, or Workflows for heavy tasks\n\n### \"Local Testing Not Working\"\n\n**Problem:** `/__scheduled` endpoint returns 404 or doesn't trigger handler \n**Cause:** Missing `scheduled()` export, wrangler not running, or incorrect endpoint format \n**Solution:**\n\n1. Verify `scheduled()` is exported:\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n console.log(\"Cron triggered\");\n },\n};\n```\n\n2. Start dev server:\n```bash\nnpx wrangler dev\n```\n\n3. Use correct endpoint format (URL-encode spaces as `+`):\n```bash\n# Correct\ncurl \"http://localhost:8787/__scheduled?cron=*/5+*+*+*+*\"\n\n# Wrong (will fail)\ncurl \"http://localhost:8787/__scheduled?cron=*/5 * * * *\"\n```\n\n4. Update Wrangler if outdated:\n```bash\nnpm install -g wrangler@latest\n```\n\n### \"waitUntil() Tasks Not Completing\"\n\n**Problem:** Background tasks in `ctx.waitUntil()` fail silently or don't execute \n**Cause:** Promises rejected without error handling, or handler returns before promise settles \n**Solution:** Always await or handle errors in waitUntil promises:\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n // BAD: Silent failures\n ctx.waitUntil(riskyOperation());\n \n // GOOD: Explicit error handling\n ctx.waitUntil(\n riskyOperation().catch(err => {\n console.error(\"Background task failed:\", err);\n return logError(err, env);\n })\n );\n },\n};\n```\n\n### \"Idempotency Issues\"\n\n**Problem:** At-least-once delivery causes duplicate side effects (double charges, duplicate emails) \n**Cause:** No deduplication mechanism \n**Solution:** Use KV to track execution IDs:\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const executionId = `${controller.cron}-${controller.scheduledTime}`;\n const existing = await env.EXECUTIONS.get(executionId);\n \n if (existing) {\n console.log(\"Already executed, skipping\");\n controller.noRetry();\n return;\n }\n \n await env.EXECUTIONS.put(executionId, \"1\", { expirationTtl: 86400 }); // 24h TTL\n await performIdempotentOperation(env);\n },\n};\n```\n\n### \"Security Concerns\"\n\n**Problem:** `__scheduled` endpoint exposed in production allows unauthorized cron triggering \n**Cause:** Testing endpoint available in deployed Workers \n**Solution:** Block `__scheduled` in production:\n\n```typescript\nexport default {\n async fetch(request, env, ctx) {\n const url = new URL(request.url);\n \n // Block __scheduled in production\n if (url.pathname === \"/__scheduled\" && env.ENVIRONMENT === \"production\") {\n return new Response(\"Not Found\", { status: 404 });\n }\n \n return handleRequest(request, env, ctx);\n },\n \n async scheduled(controller, env, ctx) {\n // Your cron logic\n },\n};\n```\n\n**Also:** Use `env.API_KEY` for secrets (never hardcode)\n\n**Alternative:** Add middleware to verify request origin:\n```typescript\nexport default {\n async fetch(request, env, ctx) {\n const url = new URL(request.url);\n \n if (url.pathname === \"/__scheduled\") {\n // Check Cloudflare headers to verify internal request\n const cfRay = request.headers.get(\"cf-ray\");\n if (!cfRay && env.ENVIRONMENT === \"production\") {\n return new Response(\"Not Found\", { status: 404 });\n }\n }\n \n return handleRequest(request, env, ctx);\n },\n \n async scheduled(controller, env, ctx) {\n // Your cron logic\n },\n};\n```\n\n## Limits & Quotas\n\n| Limit | Free | Paid | Notes |\n|-------|------|------|-------|\n| Triggers per Worker | 3 | Unlimited | Maximum cron schedules per Worker |\n| CPU time | 10ms | 50ms | May need `ctx.waitUntil()` or Workflows |\n| Execution guarantee | At-least-once | At-least-once | Duplicates possible - use idempotency |\n| Propagation delay | Up to 15 minutes | Up to 15 minutes | Time for changes to take effect globally |\n| Min interval | 1 minute | 1 minute | Cannot schedule more frequently |\n| Cron accuracy | ±1 minute | ±1 minute | Execution may drift slightly |\n\n## Testing Best Practices\n\n**Unit tests:**\n- Mock `ScheduledController`, `ExecutionContext`, and bindings\n- Test each cron expression separately\n- Verify `noRetry()` is called when expected\n- Use Vitest with `@cloudflare/vitest-pool-workers` for realistic env\n\n**Integration tests:**\n- Test via `/__scheduled` endpoint in dev environment\n- Verify idempotency logic with duplicate `scheduledTime` values\n- Test error handling and retry behavior\n\n**Production:** Start with long intervals (`*/30 * * * *`), monitor Cron Events for 24h, set up alerts before reducing interval\n\n## Resources\n\n- [Cron Triggers Docs](https://developers.cloudflare.com/workers/configuration/cron-triggers/)\n- [Scheduled Handler API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)\n- [Cloudflare Workflows](https://developers.cloudflare.com/workflows/)\n- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)\n- [Crontab Guru](https://crontab.guru/) - Validator\n- [Vitest Pool Workers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/cron-triggers/patterns.md", "content": "# Cron Triggers Patterns\n\n## API Data Sync\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const response = await fetch(\"https://api.example.com/data\", {headers: { \"Authorization\": `Bearer ${env.API_KEY}` }});\n if (!response.ok) throw new Error(`API error: ${response.status}`);\n ctx.waitUntil(env.MY_KV.put(\"cached_data\", JSON.stringify(await response.json()), {expirationTtl: 3600}));\n },\n};\n```\n\n## Database Cleanup\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const result = await env.DB.prepare(`DELETE FROM sessions WHERE expires_at < datetime('now')`).run();\n console.log(`Deleted ${result.meta.changes} expired sessions`);\n ctx.waitUntil(env.DB.prepare(\"VACUUM\").run());\n },\n};\n```\n\n## Report Generation\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const startOfWeek = new Date(); startOfWeek.setDate(startOfWeek.getDate() - 7);\n const { results } = await env.DB.prepare(`SELECT date, revenue, orders FROM daily_stats WHERE date >= ? ORDER BY date`).bind(startOfWeek.toISOString()).all();\n const report = {period: \"weekly\", totalRevenue: results.reduce((sum, d) => sum + d.revenue, 0), totalOrders: results.reduce((sum, d) => sum + d.orders, 0), dailyBreakdown: results};\n const reportKey = `reports/weekly-${Date.now()}.json`;\n await env.REPORTS_BUCKET.put(reportKey, JSON.stringify(report));\n ctx.waitUntil(env.SEND_EMAIL.fetch(\"https://example.com/send\", {method: \"POST\", body: JSON.stringify({to: \"team@example.com\", subject: \"Weekly Report\", reportUrl: `https://reports.example.com/${reportKey}`})}));\n },\n};\n```\n\n## Health Checks\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const services = [{name: \"API\", url: \"https://api.example.com/health\"}, {name: \"CDN\", url: \"https://cdn.example.com/health\"}];\n const checks = await Promise.all(services.map(async (service) => {\n const start = Date.now();\n try {\n const response = await fetch(service.url, { signal: AbortSignal.timeout(5000) });\n return {name: service.name, status: response.ok ? \"up\" : \"down\", responseTime: Date.now() - start};\n } catch (error) {\n return {name: service.name, status: \"down\", responseTime: Date.now() - start, error: error.message};\n }\n }));\n ctx.waitUntil(env.STATUS_KV.put(\"health_status\", JSON.stringify(checks)));\n const failures = checks.filter(c => c.status === \"down\");\n if (failures.length > 0) ctx.waitUntil(fetch(env.ALERT_WEBHOOK, {method: \"POST\", body: JSON.stringify({text: `${failures.length} service(s) down: ${failures.map(f => f.name).join(\", \")}`})}));\n },\n};\n```\n\n## Batch Processing (Rate-Limited)\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const queueData = await env.QUEUE_KV.get(\"pending_items\", \"json\");\n if (!queueData || queueData.length === 0) return;\n const batch = queueData.slice(0, 100);\n const results = await Promise.allSettled(batch.map(item => fetch(\"https://api.example.com/process\", {method: \"POST\", headers: {\"Authorization\": `Bearer ${env.API_KEY}`, \"Content-Type\": \"application/json\"}, body: JSON.stringify(item)})));\n console.log(`Processed ${results.filter(r => r.status === \"fulfilled\").length}/${batch.length} items`);\n ctx.waitUntil(env.QUEUE_KV.put(\"pending_items\", JSON.stringify(queueData.slice(100))));\n },\n};\n```\n\n## Queue Integration\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const batch = await env.MY_QUEUE.receive({ batchSize: 100 });\n const results = await Promise.allSettled(batch.messages.map(async (msg) => {\n await processMessage(msg.body, env);\n await msg.ack();\n }));\n console.log(`Processed ${results.filter(r => r.status === \"fulfilled\").length}/${batch.messages.length}`);\n },\n};\n```\n\n## Monitoring & Observability\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const startTime = Date.now();\n const meta = { cron: controller.cron, scheduledTime: controller.scheduledTime };\n console.log(\"[START]\", meta);\n try {\n const result = await performTask(env);\n console.log(\"[SUCCESS]\", { ...meta, duration: Date.now() - startTime, count: result.count });\n ctx.waitUntil(env.METRICS.put(`cron:${controller.scheduledTime}`, JSON.stringify({ ...meta, status: \"success\" }), { expirationTtl: 2592000 }));\n } catch (error) {\n console.error(\"[ERROR]\", { ...meta, duration: Date.now() - startTime, error: error.message });\n ctx.waitUntil(fetch(env.ALERT_WEBHOOK, { method: \"POST\", body: JSON.stringify({ text: `Cron failed: ${controller.cron}`, error: error.message }) }));\n throw error;\n }\n },\n};\n```\n\n**View logs:** `npx wrangler tail` or Dashboard → Workers & Pages → Worker → Logs\n\n## Durable Objects Coordination\n\n```typescript\nexport default {\n async scheduled(controller, env, ctx) {\n const stub = env.COORDINATOR.get(env.COORDINATOR.idFromName(\"cron-lock\"));\n const acquired = await stub.tryAcquireLock(controller.scheduledTime);\n if (!acquired) {\n controller.noRetry();\n return;\n }\n try {\n await performTask(env);\n } finally {\n await stub.releaseLock();\n }\n },\n};\n```\n\n## Python Handler\n\n```python\nfrom workers import WorkerEntrypoint\n\nclass Default(WorkerEntrypoint):\n async def scheduled(self, controller, env, ctx):\n data = await env.MY_KV.get(\"key\")\n ctx.waitUntil(env.DB.execute(\"DELETE FROM logs WHERE created_at < datetime('now', '-7 days')\"))\n```\n\n## Testing Patterns\n\n**Local testing with /__scheduled:**\n```bash\n# Start dev server\nnpx wrangler dev\n\n# Test specific cron\ncurl \"http://localhost:8787/__scheduled?cron=*/5+*+*+*+*\"\n\n# Test with specific time\ncurl \"http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000\"\n```\n\n**Unit tests:**\n```typescript\n// test/scheduled.test.ts\nimport { describe, it, expect, vi } from \"vitest\";\nimport { env } from \"cloudflare:test\";\nimport worker from \"../src/index\";\n\ndescribe(\"Scheduled Handler\", () => {\n it(\"executes cron\", async () => {\n const controller = { scheduledTime: Date.now(), cron: \"*/5 * * * *\", type: \"scheduled\" as const, noRetry: vi.fn() };\n const ctx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() };\n await worker.scheduled(controller, env, ctx);\n expect(await env.MY_KV.get(\"last_run\")).toBeDefined();\n });\n \n it(\"calls noRetry on duplicate\", async () => {\n const controller = { scheduledTime: 1704067200000, cron: \"0 2 * * *\", type: \"scheduled\" as const, noRetry: vi.fn() };\n await env.EXECUTIONS.put(\"0 2 * * *-1704067200000\", \"1\");\n await worker.scheduled(controller, env, { waitUntil: vi.fn(), passThroughOnException: vi.fn() });\n expect(controller.noRetry).toHaveBeenCalled();\n });\n});\n```\n\n## See Also\n\n- [README.md](./README.md) - Overview\n- [api.md](./api.md) - Handler implementation\n- [gotchas.md](./gotchas.md) - Troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/d1/README.md", "content": "# Cloudflare D1 Database\n\nExpert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.\n\n## Overview\n\nD1 is Cloudflare's managed, serverless database with:\n- SQLite SQL semantics and compatibility\n- Built-in disaster recovery via Time Travel (30-day point-in-time recovery)\n- Horizontal scale-out architecture (10 GB per database)\n- Worker and HTTP API access\n- Pricing based on query and storage costs only\n\n**Architecture Philosophy**: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.\n\n## Quick Start\n\n```bash\n# Create database\nwrangler d1 create \n\n# Execute migration\nwrangler d1 migrations apply --remote\n\n# Local development\nwrangler dev\n```\n\n## Core Query Methods\n\n```typescript\n// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value\n// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)\nconst { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();\nconst user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n```\n\n## Batch Operations\n\n```typescript\n// Multiple queries in single round trip (atomic transaction)\nconst results = await env.DB.batch([\n env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),\n env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),\n env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)\n]);\n```\n\n## Sessions API (Paid Plans)\n\n```typescript\n// Create long-running session for analytics/migrations (up to 15 minutes)\nconst session = env.DB.withSession();\ntry {\n await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run();\n await session.prepare('ANALYZE').run();\n} finally {\n session.close(); // Always close to release resources\n}\n```\n\n## Read Replication (Paid Plans)\n\n```typescript\n// Read from nearest replica for lower latency (automatic failover)\nconst user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n\n// Writes always go to primary\nawait env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();\n```\n\n## Platform Limits\n\n| Limit | Free Tier | Paid Plans |\n|-------|-----------|------------|\n| Database size | 500 MB | 10 GB per database |\n| Row size | 1 MB max | 1 MB max |\n| Query timeout | 30 seconds | 30 seconds |\n| Batch size | 1,000 statements | 10,000 statements |\n| Time Travel retention | 7 days | 30 days |\n| Read replicas | Not available | Yes (paid add-on) |\n\n**Pricing**: $5/month per database beyond free tier + $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month\n\n## CLI Commands\n\n```bash\n# Database management\nwrangler d1 create \nwrangler d1 list\nwrangler d1 delete \n\n# Migrations\nwrangler d1 migrations create # Create new migration file\nwrangler d1 migrations apply --remote # Apply pending migrations\nwrangler d1 migrations apply --local # Apply locally\nwrangler d1 migrations list --remote # Show applied migrations\n\n# Direct SQL execution\nwrangler d1 execute --remote --command=\"SELECT * FROM users\"\nwrangler d1 execute --local --file=./schema.sql\n\n# Backups & Import/Export\nwrangler d1 export --remote --output=./backup.sql # Full export with schema\nwrangler d1 export --remote --no-schema --output=./data.sql # Data only\nwrangler d1 time-travel restore --timestamp=\"2024-01-15T14:30:00Z\" # Point-in-time recovery\n\n# Development\nwrangler dev --persist-to=./.wrangler/state\n```\n\n## Reading Order\n\n**Start here**: Quick Start above → configuration.md (setup) → api.md (queries)\n\n**Common tasks**:\n- First time setup: configuration.md → Run migrations\n- Adding queries: api.md → Prepared statements\n- Pagination/caching: patterns.md\n- Production optimization: Read Replication + Sessions API (this file)\n- Debugging: gotchas.md\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev\n- [api.md](./api.md) - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling\n- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant, sessions, analytics\n- [gotchas.md](./gotchas.md) - SQL injection, limits by plan tier, performance, common errors\n\n## See Also\n\n- [workers](../workers/) - Worker runtime and fetch handler patterns\n- [hyperdrive](../hyperdrive/) - Connection pooling for external databases\n" }, { "path": "skills/.curated/cloudflare-deploy/references/d1/api.md", "content": "# D1 API Reference\n\n## Prepared Statements (Required for Security)\n\n```typescript\n// ❌ NEVER: Direct string interpolation (SQL injection risk)\nconst result = await env.DB.prepare(`SELECT * FROM users WHERE id = ${userId}`).all();\n\n// ✅ CORRECT: Prepared statements with bind()\nconst result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all();\n\n// Multiple parameters\nconst result = await env.DB.prepare('SELECT * FROM users WHERE email = ? AND active = ?').bind(email, true).all();\n```\n\n## Query Execution Methods\n\n```typescript\n// .all() - Returns all rows\nconst { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();\n// results: Array of row objects; success: boolean\n// meta: { duration: number, rows_read: number, rows_written: number }\n\n// .first() - Returns first row or null\nconst user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n\n// .first(columnName) - Returns single column value\nconst email = await env.DB.prepare('SELECT email FROM users WHERE id = ?').bind(userId).first('email');\n// Returns string | number | null\n\n// .run() - For INSERT/UPDATE/DELETE (no row data returned)\nconst result = await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();\n// result.meta: { duration, rows_read, rows_written, last_row_id, changes }\n\n// .raw() - Returns array of arrays (efficient for large datasets)\nconst rawResults = await env.DB.prepare('SELECT id, name FROM users').raw();\n// [[1, 'Alice'], [2, 'Bob']]\n```\n\n## Batch Operations\n\n```typescript\n// Execute multiple queries in single round trip (atomic transaction)\nconst results = await env.DB.batch([\n env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),\n env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),\n env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)\n]);\n// results is array: [result1, result2, result3]\n\n// Batch with same prepared statement, different params\nconst userIds = [1, 2, 3];\nconst stmt = env.DB.prepare('SELECT * FROM users WHERE id = ?');\nconst results = await env.DB.batch(userIds.map(id => stmt.bind(id)));\n```\n\n## Transactions (via batch)\n\n```typescript\n// D1 executes batch() as atomic transaction - all succeed or all fail\nconst results = await env.DB.batch([\n env.DB.prepare('INSERT INTO accounts (id, balance) VALUES (?, ?)').bind(1, 100),\n env.DB.prepare('INSERT INTO accounts (id, balance) VALUES (?, ?)').bind(2, 200),\n env.DB.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?').bind(50, 1),\n env.DB.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?').bind(50, 2)\n]);\n```\n\n## Sessions API (Paid Plans)\n\nLong-running sessions for operations exceeding 30s timeout (up to 15 min).\n\n```typescript\nconst session = env.DB.withSession({ timeout: 600 }); // 10 min (1-900s)\ntry {\n await session.prepare('CREATE INDEX idx_large ON big_table(column)').run();\n await session.prepare('ANALYZE').run();\n} finally {\n session.close(); // CRITICAL: always close to prevent leaks\n}\n```\n\n**Use cases**: Migrations, ANALYZE, large index creation, bulk transformations\n\n## Read Replication (Paid Plans)\n\nRoutes queries to nearest replica for lower latency. Writes always go to primary.\n\n```typescript\ninterface Env {\n DB: D1Database; // Primary (writes)\n DB_REPLICA: D1Database; // Replica (reads)\n}\n\n// Reads: use replica\nconst user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n\n// Writes: use primary\nawait env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();\n\n// Read-after-write: use primary for consistency (replication lag <100ms-2s)\nawait env.DB.prepare('INSERT INTO posts (title) VALUES (?)').bind(title).run();\nconst post = await env.DB.prepare('SELECT * FROM posts WHERE title = ?').bind(title).first(); // Primary\n```\n\n## Error Handling\n\n```typescript\nasync function getUser(userId: number, env: Env): Promise {\n try {\n const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all();\n if (!result.success) return new Response('Database error', { status: 500 });\n if (result.results.length === 0) return new Response('User not found', { status: 404 });\n return Response.json(result.results[0]);\n } catch (error) {\n return new Response('Internal error', { status: 500 });\n }\n}\n\n// Constraint violations\ntry {\n await env.DB.prepare('INSERT INTO users (email, name) VALUES (?, ?)').bind(email, name).run();\n} catch (error) {\n if (error.message?.includes('UNIQUE constraint failed')) return new Response('Email exists', { status: 409 });\n throw error;\n}\n```\n\n## REST API (HTTP) Access\n\nAccess D1 from external services (non-Worker contexts) using Cloudflare API.\n\n```typescript\n// Single query\nconst response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database/${DATABASE_ID}/query`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${CLOUDFLARE_API_TOKEN}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n sql: 'SELECT * FROM users WHERE id = ?',\n params: [userId]\n })\n }\n);\n\nconst { result, success, errors } = await response.json();\n// result: [{ results: [...], success: true, meta: {...} }]\n\n// Batch queries via HTTP\nconst response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database/${DATABASE_ID}/query`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${CLOUDFLARE_API_TOKEN}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify([\n { sql: 'SELECT * FROM users WHERE id = ?', params: [1] },\n { sql: 'SELECT * FROM posts WHERE author_id = ?', params: [1] }\n ])\n }\n);\n```\n\n**Use cases**: Server-side scripts, CI/CD migrations, administrative tools, non-Worker integrations\n\n## Testing & Debugging\n\n```typescript\n// Vitest with unstable_dev\nimport { unstable_dev } from 'wrangler';\ndescribe('D1', () => {\n let worker: Awaited>;\n beforeAll(async () => { worker = await unstable_dev('src/index.ts'); });\n afterAll(async () => { await worker.stop(); });\n it('queries users', async () => { expect((await worker.fetch('/users')).status).toBe(200); });\n});\n\n// Debug query performance\nconst result = await env.DB.prepare('SELECT * FROM users').all();\nconsole.log('Duration:', result.meta.duration, 'ms');\n\n// Query plan analysis\nconst plan = await env.DB.prepare('EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?').bind(email).all();\n```\n\n```bash\n# Inspect local database\nsqlite3 .wrangler/state/v3/d1/.sqlite\n.tables; .schema users; PRAGMA table_info(users);\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/d1/configuration.md", "content": "# D1 Configuration\n\n## wrangler.jsonc Setup\n\n```jsonc\n{\n \"name\": \"your-worker-name\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \"d1_databases\": [\n {\n \"binding\": \"DB\", // Env variable name\n \"database_name\": \"your-db-name\", // Human-readable name\n \"database_id\": \"your-database-id\", // UUID from dashboard/CLI\n \"migrations_dir\": \"migrations\" // Optional: default is \"migrations\"\n },\n // Read replica (paid plans only)\n {\n \"binding\": \"DB_REPLICA\",\n \"database_name\": \"your-db-name\",\n \"database_id\": \"your-database-id\" // Same ID, different binding\n },\n // Multiple databases\n {\n \"binding\": \"ANALYTICS_DB\",\n \"database_name\": \"analytics-db\",\n \"database_id\": \"yyy-yyy-yyy\"\n }\n ]\n}\n```\n\n## TypeScript Types\n\n```typescript\ninterface Env { DB: D1Database; ANALYTICS_DB?: D1Database; }\n\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const result = await env.DB.prepare('SELECT * FROM users').all();\n return Response.json(result.results);\n }\n}\n```\n\n## Migrations\n\nFile structure: `migrations/0001_initial_schema.sql`, `0002_add_posts.sql`, etc.\n\n### Example Migration\n\n```sql\n-- migrations/0001_initial_schema.sql\nCREATE TABLE IF NOT EXISTS users (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n email TEXT UNIQUE NOT NULL,\n name TEXT NOT NULL,\n created_at TEXT DEFAULT CURRENT_TIMESTAMP,\n updated_at TEXT DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE INDEX idx_users_email ON users(email);\n\nCREATE TABLE IF NOT EXISTS posts (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n user_id INTEGER NOT NULL,\n title TEXT NOT NULL,\n content TEXT,\n published BOOLEAN DEFAULT 0,\n created_at TEXT DEFAULT CURRENT_TIMESTAMP,\n FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE\n);\n\nCREATE INDEX idx_posts_user_id ON posts(user_id);\nCREATE INDEX idx_posts_published ON posts(published);\n```\n\n### Running Migrations\n\n```bash\n# Create new migration file\nwrangler d1 migrations create add_users_table\n# Creates: migrations/0001_add_users_table.sql\n\n# Apply migrations\nwrangler d1 migrations apply --local # Apply to local DB\nwrangler d1 migrations apply --remote # Apply to production DB\n\n# List applied migrations\nwrangler d1 migrations list --remote\n\n# Direct SQL execution (bypasses migration tracking)\nwrangler d1 execute --remote --command=\"SELECT * FROM users\"\nwrangler d1 execute --local --file=./schema.sql\n```\n\n**Migration tracking**: Wrangler creates `d1_migrations` table automatically to track applied migrations\n\n## Indexing Strategy\n\n```sql\n-- Index frequently queried columns\nCREATE INDEX idx_users_email ON users(email);\n\n-- Composite indexes for multi-column queries\nCREATE INDEX idx_posts_user_published ON posts(user_id, published);\n\n-- Covering indexes (include queried columns)\nCREATE INDEX idx_users_email_name ON users(email, name);\n\n-- Partial indexes for filtered queries\nCREATE INDEX idx_active_users ON users(email) WHERE active = 1;\n\n-- Check if query uses index\nEXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?;\n```\n\n## Drizzle ORM\n\n```typescript\n// drizzle.config.ts\nexport default {\n schema: './src/schema.ts', out: './migrations', dialect: 'sqlite', driver: 'd1-http',\n dbCredentials: { accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, databaseId: process.env.D1_DATABASE_ID!, token: process.env.CLOUDFLARE_API_TOKEN! }\n} satisfies Config;\n\n// schema.ts\nimport { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';\nexport const users = sqliteTable('users', {\n id: integer('id').primaryKey({ autoIncrement: true }),\n email: text('email').notNull().unique(),\n name: text('name').notNull()\n});\n\n// worker.ts\nimport { drizzle } from 'drizzle-orm/d1';\nimport { users } from './schema';\nexport default {\n async fetch(request: Request, env: Env) {\n const db = drizzle(env.DB);\n return Response.json(await db.select().from(users));\n }\n}\n```\n\n## Import & Export\n\n```bash\n# Export full database (schema + data)\nwrangler d1 export --remote --output=./backup.sql\n\n# Export data only (no schema)\nwrangler d1 export --remote --no-schema --output=./data-only.sql\n\n# Export with foreign key constraints preserved\n# (Default: foreign keys are disabled during export for import compatibility)\n\n# Import SQL file\nwrangler d1 execute --remote --file=./backup.sql\n\n# Limitations\n# - BLOB data may not export correctly (use R2 for binary files)\n# - Very large exports (>1GB) may timeout (split into chunks)\n# - Import is NOT atomic (use batch() for transactional imports in Workers)\n```\n\n## Plan Tiers\n\n| Feature | Free | Paid |\n|---------|------|------|\n| Database size | 500 MB | 10 GB |\n| Batch size | 1,000 statements | 10,000 statements |\n| Time Travel | 7 days | 30 days |\n| Read replicas | ❌ | ✅ |\n| Sessions API | ❌ | ✅ (up to 15 min) |\n| Pricing | Free | $5/mo + usage |\n\n**Usage pricing** (paid plans): $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month\n\n## Local Development\n\n```bash\nwrangler dev --persist-to=./.wrangler/state # Persist across restarts\n# Local DB: .wrangler/state/v3/d1/.sqlite\nsqlite3 .wrangler/state/v3/d1/.sqlite # Inspect\n\n# Local dev uses free tier limits by default\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/d1/gotchas.md", "content": "# D1 Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"SQL Injection Vulnerability\"\n\n**Cause:** Using string interpolation instead of prepared statements with bind() \n**Solution:** ALWAYS use prepared statements: `env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).all()` instead of string interpolation which allows attackers to inject malicious SQL\n\n### \"no such table\"\n\n**Cause:** Table doesn't exist because migrations haven't been run, or using wrong database binding \n**Solution:** Run migrations using `wrangler d1 migrations apply --remote` and verify binding name in wrangler.jsonc matches code\n\n### \"UNIQUE constraint failed\"\n\n**Cause:** Attempting to insert duplicate value in column with UNIQUE constraint \n**Solution:** Catch error and return 409 Conflict status code\n\n### \"Query Timeout (30s exceeded)\"\n\n**Cause:** Query execution exceeds 30 second timeout limit \n**Solution:** Break into smaller queries, add indexes to speed up queries, or reduce dataset size\n\n### \"N+1 Query Problem\"\n\n**Cause:** Making multiple individual queries in a loop instead of single optimized query \n**Solution:** Use JOIN to fetch related data in single query or use `batch()` method for multiple queries\n\n### \"Missing Indexes\"\n\n**Cause:** Queries performing full table scans without indexes \n**Solution:** Use `EXPLAIN QUERY PLAN` to check if index is used, then create index with `CREATE INDEX idx_users_email ON users(email)`\n\n### \"Boolean Type Issues\"\n\n**Cause:** SQLite uses INTEGER (0/1) not native boolean type \n**Solution:** Bind 1 or 0 instead of true/false when working with boolean values\n\n### \"Date/Time Type Issues\"\n\n**Cause:** SQLite doesn't have native DATE/TIME types \n**Solution:** Use TEXT (ISO 8601 format) or INTEGER (unix timestamp) for date/time values\n\n## Plan Tier Limits\n\n| Limit | Free Tier | Paid Plans | Notes |\n|-------|-----------|------------|-------|\n| Database size | 500 MB | 10 GB | Design for multiple DBs per tenant on paid |\n| Row size | 1 MB | 1 MB | Store large files in R2, not D1 |\n| Query timeout | 30s | 30s (900s with sessions) | Use sessions API for migrations |\n| Batch size | 1,000 statements | 10,000 statements | Split large batches accordingly |\n| Time Travel | 7 days | 30 days | Point-in-time recovery window |\n| Read replicas | ❌ Not available | ✅ Available | Paid add-on for lower latency |\n| Sessions API | ❌ Not available | ✅ Up to 15 min | For migrations and heavy operations |\n| Concurrent requests | 10,000/min | Higher | Contact support for custom limits |\n\n## Production Gotchas\n\n### \"Batch size exceeded\"\n\n**Cause:** Attempting to send >1,000 statements on free tier or >10,000 on paid \n**Solution:** Chunk batches: `for (let i = 0; i < stmts.length; i += MAX_BATCH) await env.DB.batch(stmts.slice(i, i + MAX_BATCH))`\n\n### \"Session not closed / resource leak\"\n\n**Cause:** Forgot to call `session.close()` after using sessions API \n**Solution:** Always use try/finally block: `try { await session.prepare(...) } finally { session.close() }`\n\n### \"Replication lag causing stale reads\"\n\n**Cause:** Reading from replica immediately after write - replication lag can be 100ms-2s \n**Solution:** Use primary for read-after-write: `await env.DB.prepare(...)` not `env.DB_REPLICA`\n\n### \"Migration applied to local but not remote\"\n\n**Cause:** Forgot `--remote` flag when applying migrations \n**Solution:** Always run `wrangler d1 migrations apply --remote` for production\n\n### \"Foreign key constraint failed\"\n\n**Cause:** Inserting row with FK to non-existent parent, or deleting parent before children \n**Solution:** Enable FK enforcement: `PRAGMA foreign_keys = ON;` and use ON DELETE CASCADE in schema\n\n### \"BLOB data corrupted on export\"\n\n**Cause:** D1 export may not handle BLOB correctly \n**Solution:** Store binary files in R2, only store R2 URLs/keys in D1\n\n### \"Database size approaching limit\"\n\n**Cause:** Storing too much data in single database \n**Solution:** Horizontal scale-out: create per-tenant/per-user databases, archive old data, or upgrade to paid plan\n\n### \"Local dev vs production behavior differs\"\n\n**Cause:** Local uses SQLite file, production uses distributed D1 - different performance/limits \n**Solution:** Always test migrations on remote with `--remote` flag before production rollout\n" }, { "path": "skills/.curated/cloudflare-deploy/references/d1/patterns.md", "content": "# D1 Patterns & Best Practices\n\n## Pagination\n\n```typescript\nasync function getUsers({ page, pageSize }: { page: number; pageSize: number }, env: Env) {\n const offset = (page - 1) * pageSize;\n const [countResult, dataResult] = await env.DB.batch([\n env.DB.prepare('SELECT COUNT(*) as total FROM users'),\n env.DB.prepare('SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?').bind(pageSize, offset)\n ]);\n return { data: dataResult.results, total: countResult.results[0].total, page, pageSize, totalPages: Math.ceil(countResult.results[0].total / pageSize) };\n}\n```\n\n## Conditional Queries\n\n```typescript\nasync function searchUsers(filters: { name?: string; email?: string; active?: boolean }, env: Env) {\n const conditions: string[] = [], params: (string | number | boolean | null)[] = [];\n if (filters.name) { conditions.push('name LIKE ?'); params.push(`%${filters.name}%`); }\n if (filters.email) { conditions.push('email = ?'); params.push(filters.email); }\n if (filters.active !== undefined) { conditions.push('active = ?'); params.push(filters.active ? 1 : 0); }\n const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';\n return await env.DB.prepare(`SELECT * FROM users ${whereClause}`).bind(...params).all();\n}\n```\n\n## Bulk Insert\n\n```typescript\nasync function bulkInsertUsers(users: Array<{ name: string; email: string }>, env: Env) {\n const stmt = env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)');\n const batch = users.map(user => stmt.bind(user.name, user.email));\n return await env.DB.batch(batch);\n}\n```\n\n## Caching with KV\n\n```typescript\nasync function getCachedUser(userId: number, env: { DB: D1Database; CACHE: KVNamespace }) {\n const cacheKey = `user:${userId}`;\n const cached = await env.CACHE?.get(cacheKey, 'json');\n if (cached) return cached;\n const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n if (user) await env.CACHE?.put(cacheKey, JSON.stringify(user), { expirationTtl: 300 });\n return user;\n}\n```\n\n## Query Optimization\n\n```typescript\n// ✅ Use indexes in WHERE clauses\nconst users = await env.DB.prepare('SELECT * FROM users WHERE email = ?').bind(email).all();\n\n// ✅ Limit result sets\nconst recentPosts = await env.DB.prepare('SELECT * FROM posts ORDER BY created_at DESC LIMIT 100').all();\n\n// ✅ Use batch() for multiple independent queries\nconst [user, posts, comments] = await env.DB.batch([\n env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId),\n env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(userId),\n env.DB.prepare('SELECT * FROM comments WHERE user_id = ?').bind(userId)\n]);\n\n// ❌ Avoid N+1 queries\nfor (const post of posts) {\n const author = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(post.user_id).first(); // Bad: multiple round trips\n}\n\n// ✅ Use JOINs instead\nconst postsWithAuthors = await env.DB.prepare(`\n SELECT posts.*, users.name as author_name\n FROM posts\n JOIN users ON posts.user_id = users.id\n`).all();\n```\n\n## Multi-Tenant SaaS\n\n```typescript\n// Each tenant gets own database\nexport default {\n async fetch(request: Request, env: { [key: `TENANT_${string}`]: D1Database }) {\n const tenantId = request.headers.get('X-Tenant-ID');\n const data = await env[`TENANT_${tenantId}`].prepare('SELECT * FROM records').all();\n return Response.json(data.results);\n }\n}\n```\n\n## Session Storage\n\n```typescript\nasync function createSession(userId: number, token: string, env: Env) {\n const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();\n return await env.DB.prepare('INSERT INTO sessions (user_id, token, expires_at) VALUES (?, ?, ?)').bind(userId, token, expiresAt).run();\n}\n\nasync function validateSession(token: string, env: Env) {\n return await env.DB.prepare('SELECT s.*, u.email FROM sessions s JOIN users u ON s.user_id = u.id WHERE s.token = ? AND s.expires_at > CURRENT_TIMESTAMP').bind(token).first();\n}\n```\n\n## Analytics/Events\n\n```typescript\nasync function logEvent(event: { type: string; userId?: number; metadata: object }, env: Env) {\n return await env.DB.prepare('INSERT INTO events (type, user_id, metadata) VALUES (?, ?, ?)').bind(event.type, event.userId || null, JSON.stringify(event.metadata)).run();\n}\n\nasync function getEventStats(startDate: string, endDate: string, env: Env) {\n return await env.DB.prepare('SELECT type, COUNT(*) as count FROM events WHERE timestamp BETWEEN ? AND ? GROUP BY type ORDER BY count DESC').bind(startDate, endDate).all();\n}\n```\n\n## Read Replication Pattern (Paid Plans)\n\n```typescript\ninterface Env { DB: D1Database; DB_REPLICA: D1Database; }\n\nexport default {\n async fetch(request: Request, env: Env) {\n if (request.method === 'GET') {\n // Reads: use replica for lower latency\n const users = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE active = 1').all();\n return Response.json(users.results);\n }\n \n if (request.method === 'POST') {\n const { name, email } = await request.json();\n const result = await env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)').bind(name, email).run();\n \n // Read-after-write: use primary for consistency (replication lag <100ms-2s)\n const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(result.meta.last_row_id).first();\n return Response.json(user, { status: 201 });\n }\n }\n}\n```\n\n**Use replicas for**: Analytics dashboards, search results, public queries (eventual consistency OK) \n**Use primary for**: Read-after-write, financial transactions, authentication (consistency required)\n\n## Sessions API Pattern (Paid Plans)\n\n```typescript\n// Migration with long-running session (up to 15 min)\nasync function runMigration(env: Env) {\n const session = env.DB.withSession({ timeout: 600 }); // 10 min\n try {\n await session.prepare('CREATE INDEX idx_users_email ON users(email)').run();\n await session.prepare('CREATE INDEX idx_posts_user ON posts(user_id)').run();\n await session.prepare('ANALYZE').run();\n } finally {\n session.close(); // Always close to prevent leaks\n }\n}\n\n// Bulk transformation with batching\nasync function transformLargeDataset(env: Env) {\n const session = env.DB.withSession({ timeout: 900 }); // 15 min max\n try {\n const BATCH_SIZE = 1000;\n let offset = 0;\n while (true) {\n const rows = await session.prepare('SELECT id, data FROM legacy LIMIT ? OFFSET ?').bind(BATCH_SIZE, offset).all();\n if (rows.results.length === 0) break;\n const updates = rows.results.map(row => \n session.prepare('UPDATE legacy SET new_data = ? WHERE id = ?').bind(transform(row.data), row.id)\n );\n await session.batch(updates);\n offset += BATCH_SIZE;\n }\n } finally { session.close(); }\n}\n```\n\n## Time Travel & Backups\n\n```bash\nwrangler d1 time-travel restore --timestamp=\"2024-01-15T14:30:00Z\" # Point-in-time\nwrangler d1 time-travel info # List restore points (7 days free, 30 days paid)\nwrangler d1 export --remote --output=./backup.sql # Full export\nwrangler d1 export --remote --no-schema --output=./data.sql # Data only\nwrangler d1 execute --remote --file=./backup.sql # Import\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ddos/README.md", "content": "# Cloudflare DDoS Protection\n\nAutonomous, always-on protection against DDoS attacks across L3/4 and L7.\n\n## Protection Types\n\n- **HTTP DDoS (L7)**: Protects HTTP/HTTPS traffic, phase `ddos_l7`, zone/account level\n- **Network DDoS (L3/4)**: UDP/SYN/DNS floods, phase `ddos_l4`, account level only\n- **Adaptive DDoS**: Learns 7-day baseline, detects deviations, 4 profile types (Origins, User-Agents, Locations, Protocols)\n\n## Plan Availability\n\n| Feature | Free | Pro | Business | Enterprise | Enterprise Advanced |\n|---------|------|-----|----------|------------|---------------------|\n| HTTP DDoS (L7) | ✓ | ✓ | ✓ | ✓ | ✓ |\n| Network DDoS (L3/4) | ✓ | ✓ | ✓ | ✓ | ✓ |\n| Override rules | 1 | 1 | 1 | 1 | 10 |\n| Custom expressions | ✗ | ✗ | ✗ | ✗ | ✓ |\n| Log action | ✗ | ✗ | ✗ | ✗ | ✓ |\n| Adaptive DDoS | ✗ | ✗ | ✗ | ✓ | ✓ |\n| Alert filters | Basic | Basic | Basic | Advanced | Advanced |\n\n## Actions & Sensitivity\n\n- **Actions**: `block`, `managed_challenge`, `challenge`, `log` (Enterprise Advanced only)\n- **Sensitivity**: `default` (high), `medium`, `low`, `eoff` (essentially off)\n- **Override**: By category/tag or individual rule ID\n- **Scope**: Zone-level overrides take precedence over account-level\n\n## Reading Order\n\n| File | Purpose | Start Here If... |\n|------|---------|------------------|\n| [configuration.md](./configuration.md) | Dashboard setup, rule structure, adaptive profiles | You're setting up DDoS protection for the first time |\n| [api.md](./api.md) | API endpoints, SDK usage, ruleset ID discovery | You're automating configuration or need programmatic access |\n| [patterns.md](./patterns.md) | Protection strategies, defense-in-depth, dynamic response | You need implementation patterns or layered security |\n| [gotchas.md](./gotchas.md) | False positives, tuning, error handling | You're troubleshooting or optimizing existing protection |\n\n## See Also\n- [waf](../waf/) - Application-layer security rules\n- [bot-management](../bot-management/) - Bot detection and mitigation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ddos/api.md", "content": "# DDoS API\n\n## Endpoints\n\n### HTTP DDoS (L7)\n\n```typescript\n// Zone-level\nPUT /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint\nGET /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint\n\n// Account-level (Enterprise Advanced)\nPUT /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint\nGET /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint\n```\n\n### Network DDoS (L3/4)\n\n```typescript\n// Account-level only\nPUT /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint\nGET /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint\n```\n\n## TypeScript SDK\n\n**SDK Version**: Requires `cloudflare` >= 3.0.0 for ruleset phase methods.\n\n```typescript\nimport Cloudflare from \"cloudflare\";\n\nconst client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });\n\n// STEP 1: Discover managed ruleset ID (required for overrides)\nconst allRulesets = await client.rulesets.list({ zone_id: zoneId });\nconst ddosRuleset = allRulesets.result.find(\n (r) => r.kind === \"managed\" && r.phase === \"ddos_l7\"\n);\nif (!ddosRuleset) throw new Error(\"DDoS managed ruleset not found\");\nconst managedRulesetId = ddosRuleset.id;\n\n// STEP 2: Get current HTTP DDoS configuration\nconst entrypointRuleset = await client.zones.rulesets.phases.entrypoint.get(\"ddos_l7\", {\n zone_id: zoneId,\n});\n\n// STEP 3: Update HTTP DDoS ruleset with overrides\nawait client.zones.rulesets.phases.entrypoint.update(\"ddos_l7\", {\n zone_id: zoneId,\n rules: [\n {\n action: \"execute\",\n expression: \"true\",\n action_parameters: {\n id: managedRulesetId, // From discovery step\n overrides: {\n sensitivity_level: \"medium\",\n action: \"managed_challenge\",\n },\n },\n },\n ],\n});\n\n// Network DDoS (account level, L3/4)\nconst l4Rulesets = await client.rulesets.list({ account_id: accountId });\nconst l4DdosRuleset = l4Rulesets.result.find(\n (r) => r.kind === \"managed\" && r.phase === \"ddos_l4\"\n);\nconst l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get(\"ddos_l4\", {\n account_id: accountId,\n});\n```\n\n## Alert Configuration\n\n```typescript\ninterface DDoSAlertConfig {\n name: string;\n enabled: boolean;\n alert_type: \"http_ddos_attack_alert\" | \"layer_3_4_ddos_attack_alert\" \n | \"advanced_http_ddos_attack_alert\" | \"advanced_layer_3_4_ddos_attack_alert\";\n filters?: {\n zones?: string[];\n hostnames?: string[];\n requests_per_second?: number;\n packets_per_second?: number;\n megabits_per_second?: number;\n ip_prefixes?: string[]; // CIDR\n ip_addresses?: string[];\n protocols?: string[];\n };\n mechanisms: {\n email?: Array<{ id: string }>;\n webhooks?: Array<{ id: string }>;\n pagerduty?: Array<{ id: string }>;\n };\n}\n\n// Create alert\nawait fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`,\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${apiToken}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(alertConfig),\n }\n);\n```\n\n## Typed Override Examples\n\n```typescript\n// Override by category\ninterface CategoryOverride {\n action: \"execute\";\n expression: string;\n action_parameters: {\n id: string;\n overrides: {\n categories?: Array<{\n category: \"http-flood\" | \"http-anomaly\" | \"udp-flood\" | \"syn-flood\";\n sensitivity_level?: \"default\" | \"medium\" | \"low\" | \"eoff\";\n action?: \"block\" | \"managed_challenge\" | \"challenge\" | \"log\";\n }>;\n };\n };\n}\n\n// Override by rule ID\ninterface RuleOverride {\n action: \"execute\";\n expression: string;\n action_parameters: {\n id: string;\n overrides: {\n rules?: Array<{\n id: string;\n action?: \"block\" | \"managed_challenge\" | \"challenge\" | \"log\";\n sensitivity_level?: \"default\" | \"medium\" | \"low\" | \"eoff\";\n }>;\n };\n };\n}\n\n// Example: Override specific adaptive rule\nconst adaptiveOverride: RuleOverride = {\n action: \"execute\",\n expression: \"true\",\n action_parameters: {\n id: managedRulesetId,\n overrides: {\n rules: [\n { id: \"...adaptive-origins-rule-id...\", sensitivity_level: \"low\" },\n ],\n },\n },\n};\n```\n\nSee [patterns.md](./patterns.md) for complete implementation patterns.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ddos/configuration.md", "content": "# DDoS Configuration\n\n## Dashboard Setup\n\n1. Navigate to Security > DDoS\n2. Select HTTP DDoS or Network-layer DDoS\n3. Configure sensitivity & action per ruleset/category/rule\n4. Apply overrides with optional expressions (Enterprise Advanced)\n5. Enable Adaptive DDoS toggle (Enterprise/Enterprise Advanced, requires 7 days traffic history)\n\n## Rule Structure\n\n```typescript\ninterface DDoSOverride {\n description: string;\n rules: Array<{\n action: \"execute\";\n expression: string; // Custom expression (Enterprise Advanced) or \"true\" for all\n action_parameters: {\n id: string; // Managed ruleset ID (discover via api.md)\n overrides: {\n sensitivity_level?: \"default\" | \"medium\" | \"low\" | \"eoff\";\n action?: \"block\" | \"managed_challenge\" | \"challenge\" | \"log\"; // log = Enterprise Advanced only\n categories?: Array<{\n category: string; // e.g., \"http-flood\", \"udp-flood\"\n sensitivity_level?: string;\n }>;\n rules?: Array<{\n id: string;\n action?: string;\n sensitivity_level?: string;\n }>;\n };\n };\n }>;\n}\n```\n\n## Expression Availability\n\n| Plan | Custom Expressions | Example |\n|------|-------------------|---------|\n| Free/Pro/Business | ✗ | Use `\"true\"` only |\n| Enterprise | ✗ | Use `\"true\"` only |\n| Enterprise Advanced | ✓ | `ip.src in {...}`, `http.request.uri.path matches \"...\"` |\n\n## Sensitivity Mapping\n\n| UI | API | Threshold |\n|----|-----|-----------|\n| High | `default` | Most aggressive |\n| Medium | `medium` | Balanced |\n| Low | `low` | Less aggressive |\n| Essentially Off | `eoff` | Minimal mitigation |\n\n## Common Categories\n\n- `http-flood`, `http-anomaly` (L7)\n- `udp-flood`, `syn-flood`, `dns-flood` (L3/4)\n\n## Override Precedence\n\nMultiple override layers apply in this order (higher precedence wins):\n\n```\nZone-level > Account-level\nIndividual Rule > Category > Global sensitivity/action\n```\n\n**Example**: Zone rule for `/api/*` overrides account-level global settings.\n\n## Adaptive DDoS Profiles\n\n**Availability**: Enterprise, Enterprise Advanced \n**Learning period**: 7 days of traffic history required\n\n| Profile Type | Description | Detects |\n|--------------|-------------|---------|\n| **Origins** | Traffic patterns per origin server | Anomalous requests to specific origins |\n| **User-Agents** | Traffic patterns per User-Agent | Malicious/anomalous user agent strings |\n| **Locations** | Traffic patterns per geo-location | Attacks from specific countries/regions |\n| **Protocols** | Traffic patterns per protocol (L3/4) | Protocol-specific flood attacks |\n\nConfigure by targeting specific adaptive rule IDs via API (see api.md#typed-override-examples).\n\n## Alerting\n\nConfigure via Notifications:\n- Alert types: `http_ddos_attack_alert`, `layer_3_4_ddos_attack_alert`, `advanced_*` variants\n- Filters: zones, hostnames, RPS/PPS/Mbps thresholds, IPs, protocols\n- Mechanisms: email, webhooks, PagerDuty\n\nSee [api.md](./api.md#alert-configuration) for API examples.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ddos/gotchas.md", "content": "# DDoS Gotchas\n\n## Common Errors\n\n### \"False positives blocking legitimate traffic\"\n\n**Cause**: Sensitivity too high, wrong action, or missing exceptions \n**Solution**:\n1. Lower sensitivity for specific rule/category\n2. Use `log` action first to validate (Enterprise Advanced)\n3. Add exception with custom expression (e.g., allowlist IPs)\n4. Query flagged requests via GraphQL Analytics API to identify patterns\n\n### \"Attacks getting through\"\n\n**Cause**: Sensitivity too low or wrong action \n**Solution**: Increase to `default` sensitivity and use `block` action:\n```typescript\nconst config = {\n rules: [{\n expression: \"true\",\n action: \"execute\",\n action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: \"default\", action: \"block\" } },\n }],\n};\n```\n\n### \"Adaptive rules not working\"\n\n**Cause**: Insufficient traffic history (needs 7 days) \n**Solution**: Wait for baseline to establish, check dashboard for adaptive rule status\n\n### \"Zone override ignored\"\n\n**Cause**: Account overrides conflict with zone overrides \n**Solution**: Configure at zone level OR remove zone overrides to use account-level\n\n### \"Log action not available\"\n\n**Cause**: Not on Enterprise Advanced DDoS plan \n**Solution**: Use `managed_challenge` with low sensitivity for testing\n\n### \"Rule limit exceeded\"\n\n**Cause**: Too many override rules (Free/Pro/Business: 1, Enterprise Advanced: 10) \n**Solution**: Combine conditions in single expression using `and`/`or`\n\n### \"Cannot override rule\"\n\n**Cause**: Rule is read-only \n**Solution**: Check API response for read-only indicator, use different rule\n\n### \"Cannot disable DDoS protection\"\n\n**Cause**: DDoS managed rulesets cannot be fully disabled (always-on protection) \n**Solution**: Set `sensitivity_level: \"eoff\"` for minimal mitigation\n\n### \"Expression not allowed\"\n\n**Cause**: Custom expressions require Enterprise Advanced plan \n**Solution**: Use `expression: \"true\"` for all traffic, or upgrade plan\n\n### \"Managed ruleset not found\"\n\n**Cause**: Zone/account doesn't have DDoS managed ruleset, or incorrect phase \n**Solution**: Verify ruleset exists via `client.rulesets.list()`, check phase name (`ddos_l7` or `ddos_l4`)\n\n## API Error Codes\n\n| Error Code | Message | Cause | Solution |\n|------------|---------|-------|----------|\n| 10000 | Authentication error | Invalid/missing API token | Check token has DDoS permissions |\n| 81000 | Ruleset validation failed | Invalid rule structure | Verify `action_parameters.id` is managed ruleset ID |\n| 81020 | Expression not allowed | Custom expressions on wrong plan | Use `\"true\"` or upgrade to Enterprise Advanced |\n| 81021 | Rule limit exceeded | Too many override rules | Reduce rules or upgrade (Enterprise Advanced: 10) |\n| 81022 | Invalid sensitivity level | Wrong sensitivity value | Use: `default`, `medium`, `low`, `eoff` |\n| 81023 | Invalid action | Wrong action for plan | Enterprise Advanced only: `log` action |\n\n## Limits\n\n| Resource/Limit | Free/Pro/Business | Enterprise | Enterprise Advanced |\n|----------------|-------------------|------------|---------------------|\n| Override rules per zone | 1 | 1 | 10 |\n| Custom expressions | ✗ | ✗ | ✓ |\n| Log action | ✗ | ✗ | ✓ |\n| Adaptive DDoS | ✗ | ✓ | ✓ |\n| Traffic history required | - | 7 days | 7 days |\n\n## Tuning Strategy\n\n1. Start with `log` action + `medium` sensitivity\n2. Monitor for 24-48 hours\n3. Identify false positives, add exceptions\n4. Gradually increase to `default` sensitivity\n5. Change action from `log` → `managed_challenge` → `block`\n6. Document all adjustments\n\n## Best Practices\n\n- Test during low-traffic periods\n- Use zone-level for per-site tuning\n- Reference IP lists for easier management\n- Set appropriate alert thresholds (avoid noise)\n- Combine with WAF for layered defense\n- Avoid over-tuning (keep config simple)\n\nSee [patterns.md](./patterns.md) for progressive rollout examples.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/ddos/patterns.md", "content": "# DDoS Protection Patterns\n\n## Allowlist Trusted IPs\n\n```typescript\nconst config = {\n description: \"Allowlist trusted IPs\",\n rules: [{\n expression: \"ip.src in { 203.0.113.0/24 192.0.2.1 }\",\n action: \"execute\",\n action_parameters: {\n id: managedRulesetId,\n overrides: { sensitivity_level: \"eoff\" },\n },\n }],\n};\n\nawait client.accounts.rulesets.phases.entrypoint.update(\"ddos_l7\", {\n account_id: accountId,\n ...config,\n});\n```\n\n## Route-specific Sensitivity\n\n```typescript\nconst config = {\n description: \"Route-specific protection\",\n rules: [\n {\n expression: \"not http.request.uri.path matches \\\"^/api/\\\"\",\n action: \"execute\",\n action_parameters: {\n id: managedRulesetId,\n overrides: { sensitivity_level: \"default\", action: \"block\" },\n },\n },\n {\n expression: \"http.request.uri.path matches \\\"^/api/\\\"\",\n action: \"execute\",\n action_parameters: {\n id: managedRulesetId,\n overrides: { sensitivity_level: \"low\", action: \"managed_challenge\" },\n },\n },\n ],\n};\n```\n\n## Progressive Enhancement\n\n```typescript\nenum ProtectionLevel { MONITORING = \"monitoring\", LOW = \"low\", MEDIUM = \"medium\", HIGH = \"high\" }\n\nconst levelConfig = {\n [ProtectionLevel.MONITORING]: { action: \"log\", sensitivity: \"eoff\" },\n [ProtectionLevel.LOW]: { action: \"managed_challenge\", sensitivity: \"low\" },\n [ProtectionLevel.MEDIUM]: { action: \"managed_challenge\", sensitivity: \"medium\" },\n [ProtectionLevel.HIGH]: { action: \"block\", sensitivity: \"default\" },\n} as const;\n\nasync function setProtectionLevel(zoneId: string, level: ProtectionLevel, rulesetId: string, client: Cloudflare) {\n const settings = levelConfig[level];\n return client.zones.rulesets.phases.entrypoint.update(\"ddos_l7\", {\n zone_id: zoneId,\n rules: [{\n expression: \"true\",\n action: \"execute\",\n action_parameters: { id: rulesetId, overrides: { action: settings.action, sensitivity_level: settings.sensitivity } },\n }],\n });\n}\n```\n\n## Dynamic Response to Attacks\n\n```typescript\ninterface Env { CLOUDFLARE_API_TOKEN: string; ZONE_ID: string; KV: KVNamespace; }\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n if (request.url.includes(\"/attack-detected\")) {\n const attackData = await request.json();\n await env.KV.put(`attack:${Date.now()}`, JSON.stringify(attackData), { expirationTtl: 86400 });\n const recentAttacks = await getRecentAttacks(env.KV);\n if (recentAttacks.length > 5) {\n await setProtectionLevel(env.ZONE_ID, ProtectionLevel.HIGH, managedRulesetId, client);\n return new Response(\"Protection increased\");\n }\n }\n return new Response(\"OK\");\n },\n async scheduled(event: ScheduledEvent, env: Env): Promise {\n const recentAttacks = await getRecentAttacks(env.KV);\n if (recentAttacks.length === 0) await setProtectionLevel(env.ZONE_ID, ProtectionLevel.MEDIUM, managedRulesetId, client);\n },\n};\n```\n\n## Multi-rule Tiered Protection (Enterprise Advanced)\n\n```typescript\nconst config = {\n description: \"Multi-tier DDoS protection\",\n rules: [\n {\n expression: \"not ip.src in $known_ips and not cf.bot_management.score gt 30\",\n action: \"execute\",\n action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: \"default\", action: \"block\" } },\n },\n {\n expression: \"cf.bot_management.verified_bot\",\n action: \"execute\",\n action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: \"medium\", action: \"managed_challenge\" } },\n },\n {\n expression: \"ip.src in $trusted_ips\",\n action: \"execute\",\n action_parameters: { id: managedRulesetId, overrides: { sensitivity_level: \"low\" } },\n },\n ],\n};\n```\n\n## Defense in Depth\n\nLayered security stack: DDoS + WAF + Rate Limiting + Bot Management.\n\n```typescript\n// Layer 1: DDoS (volumetric attacks)\nawait client.zones.rulesets.phases.entrypoint.update(\"ddos_l7\", {\n zone_id: zoneId,\n rules: [{ expression: \"true\", action: \"execute\", action_parameters: { id: ddosRulesetId, overrides: { sensitivity_level: \"medium\" } } }],\n});\n\n// Layer 2: WAF (exploit protection)\nawait client.zones.rulesets.phases.entrypoint.update(\"http_request_firewall_managed\", {\n zone_id: zoneId,\n rules: [{ expression: \"true\", action: \"execute\", action_parameters: { id: wafRulesetId } }],\n});\n\n// Layer 3: Rate Limiting (abuse prevention)\nawait client.zones.rulesets.phases.entrypoint.update(\"http_ratelimit\", {\n zone_id: zoneId,\n rules: [{ expression: \"http.request.uri.path eq \\\"/api/login\\\"\", action: \"block\", ratelimit: { characteristics: [\"ip.src\"], period: 60, requests_per_period: 5 } }],\n});\n\n// Layer 4: Bot Management (automation detection)\nawait client.zones.rulesets.phases.entrypoint.update(\"http_request_sbfm\", {\n zone_id: zoneId,\n rules: [{ expression: \"cf.bot_management.score lt 30\", action: \"managed_challenge\" }],\n});\n```\n\n## Cache Strategy for DDoS Mitigation\n\nExclude query strings from cache key to counter randomized query parameter attacks.\n\n```typescript\nconst cacheRule = {\n expression: \"http.request.uri.path matches \\\"^/api/\\\"\",\n action: \"set_cache_settings\",\n action_parameters: {\n cache: true,\n cache_key: { ignore_query_strings_order: true, custom_key: { query_string: { exclude: { all: true } } } },\n },\n};\n\nawait client.zones.rulesets.phases.entrypoint.update(\"http_request_cache_settings\", { zone_id: zoneId, rules: [cacheRule] });\n```\n\n**Rationale**: Attackers randomize query strings (`?random=123456`) to bypass cache. Excluding query params ensures cache hits absorb attack traffic.\n\nSee [configuration.md](./configuration.md) for rule structure details.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/README.md", "content": "# Cloudflare Durable Objects Storage\n\nPersistent storage API for Durable Objects with SQLite and KV backends, PITR, and automatic concurrency control.\n\n## Overview\n\nDO Storage provides:\n- SQLite-backed (recommended) or KV-backed\n- SQL API + synchronous/async KV APIs\n- Automatic input/output gates (race-free)\n- 30-day point-in-time recovery (PITR)\n- Transactions and alarms\n\n**Use cases:** Stateful coordination, real-time collaboration, counters, sessions, rate limiters\n\n**Billing:** Charged by request, GB-month storage, and rowsRead/rowsWritten for SQL operations\n\n## Quick Start\n\n```typescript\nexport class Counter extends DurableObject {\n sql: SqlStorage;\n \n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n this.sql = ctx.storage.sql;\n this.sql.exec('CREATE TABLE IF NOT EXISTS data(key TEXT PRIMARY KEY, value INTEGER)');\n }\n \n async increment(): Promise {\n const result = this.sql.exec(\n 'INSERT INTO data VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + 1 RETURNING value',\n 'counter', 1\n ).one();\n return result?.value || 1;\n }\n}\n```\n\n## Storage Backends\n\n| Backend | Create Method | APIs | PITR |\n|---------|---------------|------|------|\n| SQLite (recommended) | `new_sqlite_classes` | SQL + sync KV + async KV | ✅ |\n| KV (legacy) | `new_classes` | async KV only | ❌ |\n\n## Core APIs\n\n- **SQL API** (`ctx.storage.sql`): Full SQLite with extensions (FTS5, JSON, math)\n- **Sync KV** (`ctx.storage.kv`): Synchronous key-value (SQLite only)\n- **Async KV** (`ctx.storage`): Asynchronous key-value (both backends)\n- **Transactions** (`transactionSync()`, `transaction()`)\n- **PITR** (`getBookmarkForTime()`, `onNextSessionRestoreBookmark()`)\n- **Alarms** (`setAlarm()`, `alarm()` handler)\n\n## Reading Order\n\n**New to DO storage:** configuration.md → api.md → patterns.md → gotchas.md \n**Building features:** patterns.md → api.md → gotchas.md \n**Debugging issues:** gotchas.md → api.md \n**Writing tests:** testing.md\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc migrations, SQLite vs KV setup, RPC binding\n- [api.md](./api.md) - SQL exec/cursors, KV methods, storage options, transactions, alarms, PITR\n- [patterns.md](./patterns.md) - Schema migrations, caching, rate limiting, batch processing, parent-child coordination\n- [gotchas.md](./gotchas.md) - Concurrency gates, INTEGER precision, transaction rules, SQL limits\n- [testing.md](./testing.md) - vitest-pool-workers setup, testing DOs with SQL/alarms/PITR\n\n## See Also\n\n- [durable-objects](../durable-objects/) - DO fundamentals and coordination patterns\n- [workers](../workers/) - Worker runtime for DO stubs\n- [d1](../d1/) - Shared database alternative to per-DO storage\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/api.md", "content": "# DO Storage API Reference\n\n## SQL API\n\n```typescript\nconst cursor = this.sql.exec('SELECT * FROM users WHERE email = ?', email);\nfor (let row of cursor) {} // Objects: { id, name, email }\ncursor.toArray(); cursor.one(); // Single row (throws if != 1)\nfor (let row of cursor.raw()) {} // Arrays: [1, \"Alice\", \"...\"]\n\n// Manual iteration\nconst iter = cursor[Symbol.iterator]();\nconst first = iter.next(); // { value: {...}, done: false }\n\ncursor.columnNames; // [\"id\", \"name\", \"email\"]\ncursor.rowsRead; cursor.rowsWritten; // Billing\n\ntype User = { id: number; name: string; email: string };\nconst user = this.sql.exec('...', userId).one();\n```\n\n## Sync KV API (SQLite only)\n\n```typescript\nthis.ctx.storage.kv.get(\"counter\"); // undefined if missing\nthis.ctx.storage.kv.put(\"counter\", 42);\nthis.ctx.storage.kv.put(\"user\", { name: \"Alice\", age: 30 });\nthis.ctx.storage.kv.delete(\"counter\"); // true if existed\n\nfor (let [key, value] of this.ctx.storage.kv.list()) {}\n\n// List options: start, prefix, reverse, limit\nthis.ctx.storage.kv.list({ start: \"user:\", prefix: \"user:\", reverse: true, limit: 100 });\n```\n\n## Async KV API (Both backends)\n\n```typescript\nawait this.ctx.storage.get(\"key\"); // Single\nawait this.ctx.storage.get([\"key1\", \"key2\"]); // Multiple (max 128)\nawait this.ctx.storage.put(\"key\", value); // Single\nawait this.ctx.storage.put({ \"key1\": \"v1\", \"key2\": { nested: true } }); // Multiple (max 128)\nawait this.ctx.storage.delete(\"key\");\nawait this.ctx.storage.delete([\"key1\", \"key2\"]);\nawait this.ctx.storage.list({ prefix: \"user:\", limit: 100 });\n\n// Options: allowConcurrency, noCache, allowUnconfirmed\nawait this.ctx.storage.get(\"key\", { allowConcurrency: true, noCache: true });\nawait this.ctx.storage.put(\"key\", value, { allowUnconfirmed: true, noCache: true });\n```\n\n### Storage Options\n\n| Option | Methods | Effect | Use Case |\n|--------|---------|--------|----------|\n| `allowConcurrency` | get, list | Skip input gate; allow concurrent requests during read | Read-heavy metrics that don't need strict consistency |\n| `noCache` | get, put, list | Skip in-memory cache; always read from disk | Rarely-accessed data or testing storage directly |\n| `allowUnconfirmed` | put, delete | Return before write confirms (still protected by output gate) | Non-critical writes where latency matters more than confirmation |\n\n## Transactions\n\n```typescript\n// Sync (SQL/sync KV only)\nthis.ctx.storage.transactionSync(() => {\n this.sql.exec('UPDATE accounts SET balance = balance - ? WHERE id = ?', 100, 1);\n this.sql.exec('UPDATE accounts SET balance = balance + ? WHERE id = ?', 100, 2);\n return \"result\";\n});\n\n// Async\nawait this.ctx.storage.transaction(async () => {\n const value = await this.ctx.storage.get(\"counter\");\n await this.ctx.storage.put(\"counter\", value + 1);\n if (value > 100) this.ctx.storage.rollback(); // Explicit rollback\n});\n```\n\n## Point-in-Time Recovery\n\n```typescript\nawait this.ctx.storage.getCurrentBookmark();\nawait this.ctx.storage.getBookmarkForTime(Date.now() - 2 * 24 * 60 * 60 * 1000);\nawait this.ctx.storage.onNextSessionRestoreBookmark(bookmark);\nthis.ctx.abort(); // Restart to apply; bookmarks lexically comparable (earlier < later)\n```\n\n## Alarms\n\n```typescript\nawait this.ctx.storage.setAlarm(Date.now() + 60000); // Timestamp or Date\nawait this.ctx.storage.getAlarm();\nawait this.ctx.storage.deleteAlarm();\n\nasync alarm() { await this.doScheduledWork(); }\n```\n\n## Misc\n\n```typescript\nawait this.ctx.storage.deleteAll(); // Atomic for SQLite; alarm NOT included\nthis.ctx.storage.sql.databaseSize; // Bytes\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/configuration.md", "content": "# DO Storage Configuration\n\n## SQLite-backed (Recommended)\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"migrations\": [\n {\n \"tag\": \"v1\",\n \"new_sqlite_classes\": [\"Counter\", \"Session\", \"RateLimiter\"]\n }\n ]\n}\n```\n\n**Migration lifecycle:** Migrations run once per deployment. Existing DO instances get new storage backend on next invocation. Renaming/removing classes requires `renamed_classes` or `deleted_classes` entries.\n\n## KV-backed (Legacy)\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"migrations\": [\n {\n \"tag\": \"v1\",\n \"new_classes\": [\"OldCounter\"]\n }\n ]\n}\n```\n\n## TypeScript Setup\n\n```typescript\nexport class MyDurableObject extends DurableObject {\n sql: SqlStorage;\n \n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n this.sql = ctx.storage.sql;\n \n // Initialize schema\n this.sql.exec(`\n CREATE TABLE IF NOT EXISTS users(\n id INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n email TEXT UNIQUE\n );\n `);\n }\n}\n\n// Binding\ninterface Env {\n MY_DO: DurableObjectNamespace;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const id = env.MY_DO.idFromName('singleton');\n const stub = env.MY_DO.get(id);\n \n // Modern RPC: call methods directly (recommended)\n const result = await stub.someMethod();\n return Response.json(result);\n \n // Legacy: forward request (still works)\n // return stub.fetch(request);\n }\n}\n```\n\n## CPU Limits\n\n```jsonc\n{\n \"limits\": {\n \"cpu_ms\": 300000 // 5 minutes (default 30s)\n }\n}\n```\n\n## Location Control\n\n```typescript\n// Jurisdiction (GDPR/FedRAMP)\nconst euNamespace = env.MY_DO.jurisdiction(\"eu\");\nconst id = euNamespace.newUniqueId();\nconst stub = euNamespace.get(id);\n\n// Location hint (best effort)\nconst stub = env.MY_DO.get(id, { locationHint: \"enam\" });\n// Hints: wnam, enam, sam, weur, eeur, apac, oc, afr, me\n```\n\n## Initialization\n\n```typescript\nexport class Counter extends DurableObject {\n value: number;\n \n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n \n // Block concurrent requests during init\n ctx.blockConcurrencyWhile(async () => {\n this.value = (await ctx.storage.get(\"value\")) || 0;\n });\n }\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/gotchas.md", "content": "# DO Storage Gotchas & Troubleshooting\n\n## Concurrency Model (CRITICAL)\n\nDurable Objects use **input/output gates** to prevent race conditions:\n\n### Input Gates\nBlock new requests during storage reads from CURRENT request:\n\n```typescript\n// SAFE: Input gate active during await\nasync increment() {\n const val = await this.ctx.storage.get(\"counter\"); // Input gate blocks other requests\n await this.ctx.storage.put(\"counter\", val + 1);\n return val;\n}\n```\n\n### Output Gates\nHold response until ALL writes from current request confirm:\n\n```typescript\n// SAFE: Output gate waits for put() to confirm before returning response\nasync increment() {\n const val = await this.ctx.storage.get(\"counter\");\n this.ctx.storage.put(\"counter\", val + 1); // No await\n return new Response(String(val)); // Response delayed until write confirms\n}\n```\n\n### Write Coalescing\nMultiple writes to same key = atomic (last write wins):\n\n```typescript\n// SAFE: All three writes coalesce atomically\nthis.ctx.storage.put(\"key\", 1);\nthis.ctx.storage.put(\"key\", 2);\nthis.ctx.storage.put(\"key\", 3); // Final value: 3\n```\n\n### Breaking Gates (DANGER)\n\n**fetch() breaks input/output gates** → allows request interleaving:\n\n```typescript\n// UNSAFE: fetch() allows another request to interleave\nasync unsafe() {\n const val = await this.ctx.storage.get(\"counter\");\n await fetch(\"https://api.example.com\"); // Gate broken!\n await this.ctx.storage.put(\"counter\", val + 1); // Race condition possible\n}\n```\n\n**Solution:** Use `blockConcurrencyWhile()` or `transaction()`:\n\n```typescript\n// SAFE: Block concurrent requests explicitly\nasync safe() {\n return await this.ctx.blockConcurrencyWhile(async () => {\n const val = await this.ctx.storage.get(\"counter\");\n await fetch(\"https://api.example.com\");\n await this.ctx.storage.put(\"counter\", val + 1);\n return val;\n });\n}\n```\n\n### allowConcurrency Option\n\nOpt out of input gate for reads that don't need protection:\n\n```typescript\n// Allow concurrent reads (no consistency guarantee)\nconst val = await this.ctx.storage.get(\"metrics\", { allowConcurrency: true });\n```\n\n## Common Errors\n\n### \"Race Condition in Concurrent Calls\"\n\n**Cause:** Multiple concurrent storage operations initiated from same event (e.g., `Promise.all()`) are not protected by input gate \n**Solution:** Avoid concurrent storage operations within single event; input gate only serializes requests from different events, not operations within same event\n\n### \"Direct SQL Transaction Statements\"\n\n**Cause:** Using `BEGIN TRANSACTION` directly instead of transaction methods \n**Solution:** Use `this.ctx.storage.transactionSync()` for sync operations or `this.ctx.storage.transaction()` for async operations\n\n### \"Async in transactionSync\"\n\n**Cause:** Using async operations inside `transactionSync()` callback \n**Solution:** Use async `transaction()` method instead of `transactionSync()` when async operations needed\n\n### \"TypeScript Type Mismatch at Runtime\"\n\n**Cause:** Query doesn't return all fields specified in TypeScript type \n**Solution:** Ensure SQL query selects all columns that match the TypeScript type definition\n\n### \"Silent Data Corruption with Large IDs\"\n\n**Cause:** JavaScript numbers have 53-bit precision; SQLite INTEGER is 64-bit \n**Symptom:** IDs > 9007199254740991 (Number.MAX_SAFE_INTEGER) silently truncate/corrupt \n**Solution:** Store large IDs as TEXT:\n\n```typescript\n// BAD: Snowflake/Twitter IDs will corrupt\nthis.sql.exec(\"CREATE TABLE events(id INTEGER PRIMARY KEY)\");\nthis.sql.exec(\"INSERT INTO events VALUES (?)\", 1234567890123456789n); // Corrupts!\n\n// GOOD: Store as TEXT\nthis.sql.exec(\"CREATE TABLE events(id TEXT PRIMARY KEY)\");\nthis.sql.exec(\"INSERT INTO events VALUES (?)\", \"1234567890123456789\");\n```\n\n### \"Alarm Not Deleted with deleteAll()\"\n\n**Cause:** `deleteAll()` doesn't delete alarms automatically \n**Solution:** Call `deleteAlarm()` explicitly before `deleteAll()` to remove alarm\n\n### \"Slow Performance\"\n\n**Cause:** Using async KV API instead of sync API \n**Solution:** Use sync KV API (`ctx.storage.kv`) for better performance with simple key-value operations\n\n### \"High Billing from Storage Operations\"\n\n**Cause:** Excessive `rowsRead`/`rowsWritten` or unused objects not cleaned up \n**Solution:** Monitor `rowsRead`/`rowsWritten` metrics and ensure unused objects call `deleteAll()`\n\n### \"Durable Object Overloaded\"\n\n**Cause:** Single DO exceeding ~1K req/sec soft limit \n**Solution:** Shard across multiple DOs with random IDs or other distribution strategy\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Max columns per table | 100 | SQL limitation |\n| Max string/BLOB per row | 2 MB | SQL limitation |\n| Max row size | 2 MB | SQL limitation |\n| Max SQL statement size | 100 KB | SQL limitation |\n| Max SQL parameters | 100 | SQL limitation |\n| Max LIKE/GLOB pattern | 50 B | SQL limitation |\n| SQLite storage per object | 10 GB | SQLite-backed storage |\n| SQLite key+value size | 2 MB | SQLite-backed storage |\n| KV storage per object | Unlimited | KV-style storage |\n| KV key size | 2 KiB | KV-style storage |\n| KV value size | 128 KiB | KV-style storage |\n| Request throughput | ~1K req/sec | Soft limit per DO |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/patterns.md", "content": "# DO Storage Patterns & Best Practices\n\n## Schema Migration\n\n```typescript\nexport class MyDurableObject extends DurableObject {\n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n this.sql = ctx.storage.sql;\n \n // Use SQLite's built-in user_version pragma\n const ver = this.sql.exec(\"PRAGMA user_version\").one()?.user_version || 0;\n \n if (ver === 0) {\n this.sql.exec(`CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT)`);\n this.sql.exec(\"PRAGMA user_version = 1\");\n }\n if (ver === 1) {\n this.sql.exec(`ALTER TABLE users ADD COLUMN email TEXT`);\n this.sql.exec(\"PRAGMA user_version = 2\");\n }\n }\n}\n```\n\n## In-Memory Caching\n\n```typescript\nexport class UserCache extends DurableObject {\n cache = new Map();\n async getUser(id: string): Promise {\n if (this.cache.has(id)) {\n const cached = this.cache.get(id);\n if (cached) return cached;\n }\n const user = await this.ctx.storage.get(`user:${id}`);\n if (user) this.cache.set(id, user);\n return user;\n }\n async updateUser(id: string, data: Partial) {\n const updated = { ...await this.getUser(id), ...data };\n this.cache.set(id, updated);\n await this.ctx.storage.put(`user:${id}`, updated);\n return updated;\n }\n}\n```\n\n## Rate Limiting\n\n```typescript\nexport class RateLimiter extends DurableObject {\n async checkLimit(key: string, limit: number, window: number): Promise {\n const now = Date.now();\n this.sql.exec('DELETE FROM requests WHERE key = ? AND timestamp < ?', key, now - window);\n const count = this.sql.exec('SELECT COUNT(*) as count FROM requests WHERE key = ?', key).one().count;\n if (count >= limit) return false;\n this.sql.exec('INSERT INTO requests (key, timestamp) VALUES (?, ?)', key, now);\n return true;\n }\n}\n```\n\n## Batch Processing with Alarms\n\n```typescript\nexport class BatchProcessor extends DurableObject {\n pending: string[] = [];\n async addItem(item: string) {\n this.pending.push(item);\n if (!await this.ctx.storage.getAlarm()) await this.ctx.storage.setAlarm(Date.now() + 5000);\n }\n async alarm() {\n const items = [...this.pending];\n this.pending = [];\n this.sql.exec(`INSERT INTO processed_items (item, timestamp) VALUES ${items.map(() => \"(?, ?)\").join(\", \")}`, ...items.flatMap(item => [item, Date.now()]));\n }\n}\n```\n\n## Initialization Pattern\n\n```typescript\nexport class Counter extends DurableObject {\n value: number;\n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n ctx.blockConcurrencyWhile(async () => { this.value = (await ctx.storage.get(\"value\")) || 0; });\n }\n async increment() {\n this.value++;\n this.ctx.storage.put(\"value\", this.value); // Don't await (output gate protects)\n return this.value;\n }\n}\n```\n\n## Safe Counter / Optimized Write\n\n```typescript\n// Input gate blocks other requests\nasync getUniqueNumber(): Promise {\n let val = await this.ctx.storage.get(\"counter\");\n await this.ctx.storage.put(\"counter\", val + 1);\n return val;\n}\n\n// No await on write - output gate delays response until write confirms\nasync increment(): Promise {\n let val = await this.ctx.storage.get(\"counter\");\n this.ctx.storage.put(\"counter\", val + 1);\n return new Response(String(val));\n}\n```\n\n## Parent-Child Coordination\n\nHierarchical DO pattern where parent manages child DOs:\n\n```typescript\n// Parent DO coordinates children\nexport class Workspace extends DurableObject {\n async createDocument(name: string): Promise {\n const docId = crypto.randomUUID();\n const childId = this.env.DOCUMENT.idFromName(`${this.ctx.id.toString()}:${docId}`);\n const childStub = this.env.DOCUMENT.get(childId);\n await childStub.initialize(name);\n \n // Track child in parent storage\n this.sql.exec('INSERT INTO documents (id, name, created) VALUES (?, ?, ?)', \n docId, name, Date.now());\n return docId;\n }\n \n async listDocuments(): Promise {\n return this.sql.exec('SELECT id FROM documents').toArray().map(r => r.id);\n }\n}\n\n// Child DO\nexport class Document extends DurableObject {\n async initialize(name: string) {\n this.sql.exec('CREATE TABLE IF NOT EXISTS content(key TEXT PRIMARY KEY, value TEXT)');\n this.sql.exec('INSERT INTO content VALUES (?, ?)', 'name', name);\n }\n}\n```\n\n## Write Coalescing Pattern\n\nMultiple writes to same key coalesce atomically (last write wins):\n\n```typescript\nasync updateMetrics(userId: string, actions: Action[]) {\n // All writes coalesce - no await needed\n for (const action of actions) {\n this.ctx.storage.put(`user:${userId}:lastAction`, action.type);\n this.ctx.storage.put(`user:${userId}:count`, \n await this.ctx.storage.get(`user:${userId}:count`) + 1);\n }\n // Output gate ensures all writes confirm before response\n return new Response(\"OK\");\n}\n\n// Atomic batch with SQL\nasync batchUpdate(items: Item[]) {\n this.sql.exec('BEGIN');\n for (const item of items) {\n this.sql.exec('INSERT OR REPLACE INTO items VALUES (?, ?)', item.id, item.value);\n }\n this.sql.exec('COMMIT');\n}\n```\n\n## Cleanup\n\n```typescript\nasync cleanup() {\n await this.ctx.storage.deleteAlarm(); // Separate from deleteAll\n await this.ctx.storage.deleteAll();\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/do-storage/testing.md", "content": "# DO Storage Testing\n\nTesting Durable Objects with storage using `vitest-pool-workers`.\n\n## Setup\n\n**vitest.config.ts:**\n```typescript\nimport { defineWorkersConfig } from \"@cloudflare/vitest-pool-workers/config\";\n\nexport default defineWorkersConfig({\n test: {\n poolOptions: {\n workers: { wrangler: { configPath: \"./wrangler.toml\" } }\n }\n }\n});\n```\n\n**package.json:** Add `@cloudflare/vitest-pool-workers` and `vitest` to devDependencies\n\n## Basic Testing\n\n```typescript\nimport { env, runInDurableObject } from \"cloudflare:test\";\nimport { describe, it, expect } from \"vitest\";\n\ndescribe(\"Counter DO\", () => {\n it(\"increments counter\", async () => {\n const id = env.COUNTER.idFromName(\"test\");\n const result = await runInDurableObject(env.COUNTER, id, async (instance, state) => {\n const val1 = await instance.increment();\n const val2 = await instance.increment();\n return { val1, val2 };\n });\n expect(result.val1).toBe(1);\n expect(result.val2).toBe(2);\n });\n});\n```\n\n## Testing SQL Storage\n\n```typescript\nit(\"creates and queries users\", async () => {\n const id = env.USER_MANAGER.idFromName(\"test\");\n await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {\n await instance.createUser(\"alice@example.com\", \"Alice\");\n const user = await instance.getUser(\"alice@example.com\");\n expect(user).toEqual({ email: \"alice@example.com\", name: \"Alice\" });\n });\n});\n\nit(\"handles schema migrations\", async () => {\n const id = env.USER_MANAGER.idFromName(\"migration-test\");\n await runInDurableObject(env.USER_MANAGER, id, async (instance, state) => {\n const version = state.storage.sql.exec(\n \"SELECT value FROM _meta WHERE key = 'schema_version'\"\n ).one()?.value;\n expect(version).toBe(\"1\");\n });\n});\n```\n\n## Testing Alarms\n\n```typescript\nimport { runDurableObjectAlarm } from \"cloudflare:test\";\n\nit(\"processes batch on alarm\", async () => {\n const id = env.BATCH_PROCESSOR.idFromName(\"test\");\n \n // Add items\n await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance) => {\n await instance.addItem(\"item1\");\n await instance.addItem(\"item2\");\n });\n \n // Trigger alarm\n await runDurableObjectAlarm(env.BATCH_PROCESSOR, id);\n \n // Verify processed\n await runInDurableObject(env.BATCH_PROCESSOR, id, async (instance, state) => {\n const count = state.storage.sql.exec(\n \"SELECT COUNT(*) as count FROM processed_items\"\n ).one().count;\n expect(count).toBe(2);\n });\n});\n```\n\n## Testing Concurrency\n\n```typescript\nit(\"handles concurrent increments safely\", async () => {\n const id = env.COUNTER.idFromName(\"concurrent-test\");\n \n // Parallel increments\n const results = await Promise.all([\n runInDurableObject(env.COUNTER, id, (i) => i.increment()),\n runInDurableObject(env.COUNTER, id, (i) => i.increment()),\n runInDurableObject(env.COUNTER, id, (i) => i.increment())\n ]);\n \n // All should get unique values\n expect(new Set(results).size).toBe(3);\n expect(Math.max(...results)).toBe(3);\n});\n```\n\n## Test Isolation\n\n```typescript\n// Per-test unique IDs\nlet testId: string;\nbeforeEach(() => { testId = crypto.randomUUID(); });\n\nit(\"isolated test\", async () => {\n const id = env.MY_DO.idFromName(testId);\n // Uses unique DO instance\n});\n\n// Cleanup pattern\nit(\"with cleanup\", async () => {\n const id = env.MY_DO.idFromName(\"cleanup-test\");\n try {\n await runInDurableObject(env.MY_DO, id, async (instance) => {});\n } finally {\n await runInDurableObject(env.MY_DO, id, async (instance, state) => {\n await state.storage.deleteAll();\n });\n }\n});\n```\n\n## Testing PITR\n\n```typescript\nit(\"restores from bookmark\", async () => {\n const id = env.MY_DO.idFromName(\"pitr-test\");\n \n // Create checkpoint\n const bookmark = await runInDurableObject(env.MY_DO, id, async (instance, state) => {\n await state.storage.put(\"value\", 1);\n return await state.storage.getCurrentBookmark();\n });\n \n // Modify and restore\n await runInDurableObject(env.MY_DO, id, async (instance, state) => {\n await state.storage.put(\"value\", 2);\n await state.storage.onNextSessionRestoreBookmark(bookmark);\n state.abort();\n });\n \n // Verify restored\n await runInDurableObject(env.MY_DO, id, async (instance, state) => {\n const value = await state.storage.get(\"value\");\n expect(value).toBe(1);\n });\n});\n```\n\n## Testing Transactions\n\n```typescript\nit(\"rolls back on error\", async () => {\n const id = env.BANK.idFromName(\"transaction-test\");\n \n await runInDurableObject(env.BANK, id, async (instance, state) => {\n await state.storage.put(\"balance\", 100);\n \n await expect(\n state.storage.transaction(async () => {\n await state.storage.put(\"balance\", 50);\n throw new Error(\"Cancel\");\n })\n ).rejects.toThrow(\"Cancel\");\n \n const balance = await state.storage.get(\"balance\");\n expect(balance).toBe(100); // Rolled back\n });\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/durable-objects/README.md", "content": "# Cloudflare Durable Objects\n\nExpert guidance for building stateful applications with Cloudflare Durable Objects.\n\n## Reading Order\n\n1. **First time?** Read this overview + Quick Start\n2. **Setting up?** See [Configuration](./configuration.md)\n3. **Building features?** Use decision trees below → [Patterns](./patterns.md)\n4. **Debugging issues?** Check [Gotchas](./gotchas.md)\n5. **Deep dive?** [API](./api.md) and [DO Storage](../do-storage/README.md)\n\n## Overview\n\nDurable Objects combine compute with storage in globally-unique, strongly-consistent packages:\n- **Globally unique instances**: Each DO has unique ID for multi-client coordination\n- **Co-located storage**: Fast, strongly-consistent storage with compute\n- **Automatic placement**: Objects spawn near first request location\n- **Stateful serverless**: In-memory state + persistent storage\n- **Single-threaded**: Serial request processing (no race conditions)\n\n## Rules of Durable Objects\n\nCritical rules preventing most production issues:\n\n1. **One alarm per DO** - Schedule multiple events via queue pattern\n2. **~1K req/s per DO max** - Shard for higher throughput\n3. **Constructor runs every wake** - Keep initialization light; use lazy loading\n4. **Hibernation clears memory** - In-memory state lost; persist critical data\n5. **Use `ctx.waitUntil()` for cleanup** - Ensures completion after response sent\n6. **No setTimeout for persistence** - Use `setAlarm()` for reliable scheduling\n\n## Core Concepts\n\n### Class Structure\nAll DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).\n\n### Lifecycle States\n\n```\n[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]\n ↓\n [Destroyed]\n```\n\n- **Not Created**: DO ID exists but instance never spawned\n- **Active**: Processing requests, in-memory state valid, billed per GB-hour\n- **Hibernated**: WebSocket connections open but zero compute, zero cost\n- **Evicted**: Removed from memory; next request triggers cold start\n- **Destroyed**: Data deleted via migration or manual deletion\n\n### Accessing from Workers\nWorkers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).\n\n**RPC vs fetch() decision:**\n```\n├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)\n├─ Need HTTP semantics (headers, status) → fetch()\n├─ Proxying requests to DO → fetch()\n└─ Legacy compatibility → fetch()\n```\n\nSee [Patterns: RPC vs fetch()](./patterns.md) for examples.\n\n### ID Generation\n- `idFromName()`: Deterministic, named coordination (rate limiting, locks)\n- `newUniqueId()`: Random IDs for sharding high-throughput workloads\n- `idFromString()`: Derive from existing IDs\n- Jurisdiction option: Data locality compliance\n\n### Storage Options\n\n**Which storage API?**\n```\n├─ Structured data, relations, transactions → SQLite (recommended)\n├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)\n└─ Legacy KV-only DO → ctx.storage (async KV)\n```\n\n- **SQLite** (recommended): Structured data, transactions, 10GB/DO\n- **Synchronous KV API**: Simple key-value on SQLite objects\n- **Asynchronous KV API**: Legacy/advanced use cases\n\nSee [DO Storage](../do-storage/README.md) for deep dive.\n\n### Special Features\n- **Alarms**: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)\n- **WebSocket Hibernation**: Zero-cost idle connections (memory cleared on hibernation)\n- **Point-in-Time Recovery**: Restore to any point in 30 days (SQLite only)\n\n## Quick Start\n\n```typescript\nimport { DurableObject } from \"cloudflare:workers\";\n\nexport class Counter extends DurableObject {\n async increment(): Promise {\n const result = this.ctx.storage.sql.exec(\n `INSERT INTO counters (id, value) VALUES (1, 1)\n ON CONFLICT(id) DO UPDATE SET value = value + 1\n RETURNING value`\n ).one();\n return result.value;\n }\n}\n\n// Worker access\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const id = env.COUNTER.idFromName(\"global\");\n const stub = env.COUNTER.get(id);\n const count = await stub.increment();\n return new Response(`Count: ${count}`);\n }\n};\n```\n\n## Decision Trees\n\n### What do you need?\n\n```\n├─ Coordinate requests (rate limit, lock, session)\n│ → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)\n│\n├─ High throughput (>1K req/s)\n│ → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)\n│\n├─ Real-time updates (WebSocket, chat, collab)\n│ → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)\n│\n├─ Background work (cleanup, notifications, scheduled tasks)\n│ → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)\n│\n└─ User sessions with expiration\n → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)\n```\n\n### Which access pattern?\n\n```\n├─ New project + typed methods → RPC (compat ≥2024-04-03)\n├─ Need HTTP semantics → fetch()\n├─ Proxying to DO → fetch()\n└─ Legacy compat → fetch()\n```\n\nSee [Patterns: RPC vs fetch()](./patterns.md) for examples.\n\n### Which storage?\n\n```\n├─ Structured data, SQL queries, transactions → SQLite (recommended)\n├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)\n└─ Legacy KV-only DO → ctx.storage (async API)\n```\n\nSee [DO Storage](../do-storage/README.md) for complete guide.\n\n## Essential Commands\n\n```bash\nnpx wrangler dev # Local dev with DOs\nnpx wrangler dev --remote # Test against prod DOs\nnpx wrangler deploy # Deploy + auto-apply migrations\n```\n\n## Resources\n\n**Docs**: https://developers.cloudflare.com/durable-objects/ \n**API Reference**: https://developers.cloudflare.com/durable-objects/api/ \n**Examples**: https://developers.cloudflare.com/durable-objects/examples/\n\n## In This Reference\n\n- **[Configuration](./configuration.md)** - wrangler.jsonc setup, migrations, bindings, environments\n- **[API](./api.md)** - Class structure, ctx methods, alarms, WebSocket hibernation\n- **[Patterns](./patterns.md)** - Sharding, rate limiting, locks, real-time, sessions\n- **[Gotchas](./gotchas.md)** - Limits, hibernation caveats, common errors\n\n## See Also\n\n- **[DO Storage](../do-storage/README.md)** - SQLite, KV, transactions (detailed storage guide)\n- **[Workers](../workers/README.md)** - Core Workers runtime features\n- **[WebSockets](../websockets/README.md)** - WebSocket APIs and patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/durable-objects/api.md", "content": "# Durable Objects API\n\n## Class Structure\n\n```typescript\nimport { DurableObject } from \"cloudflare:workers\";\n\nexport class MyDO extends DurableObject {\n constructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n // Runs on EVERY wake - keep light!\n }\n \n // RPC methods (called directly from worker)\n async myMethod(arg: string): Promise { return arg; }\n \n // fetch handler (legacy/HTTP semantics)\n async fetch(req: Request): Promise { /* ... */ }\n \n // Lifecycle handlers\n async alarm() { /* alarm fired */ }\n async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) { /* ... */ }\n async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { /* ... */ }\n async webSocketError(ws: WebSocket, error: unknown) { /* ... */ }\n}\n```\n\n## DurableObjectState Context Methods\n\n### Concurrency Control\n\n```typescript\n// Complete work after response sent (e.g., cleanup, logging)\nthis.ctx.waitUntil(promise: Promise): void\n\n// Critical section - blocks all other requests until complete\nawait this.ctx.blockConcurrencyWhile(async () => {\n // No other requests processed during this block\n // Use for initialization or critical operations\n})\n```\n\n**When to use:**\n- `waitUntil()`: Background cleanup, logging, non-critical work after response\n- `blockConcurrencyWhile()`: First-time init, schema migration, critical state setup\n\n### Lifecycle\n\n```typescript\nthis.ctx.id // DurableObjectId of this instance\nthis.ctx.abort() // Force eviction (use after PITR restore to reload state)\n```\n\n### Storage Access\n\n```typescript\nthis.ctx.storage.sql // SQLite API (recommended)\nthis.ctx.storage.kv // Sync KV API (SQLite DOs only)\nthis.ctx.storage // Async KV API (legacy/KV-only DOs)\n```\n\nSee **[DO Storage](../do-storage/README.md)** for complete storage API reference.\n\n### WebSocket Management\n\n```typescript\nthis.ctx.acceptWebSocket(ws: WebSocket, tags?: string[]) // Enable hibernation\nthis.ctx.getWebSockets(tag?: string): WebSocket[] // Get by tag or all\nthis.ctx.getTags(ws: WebSocket): string[] // Get tags for connection\n```\n\n### Alarms\n\n```typescript\nawait this.ctx.storage.setAlarm(timestamp: number | Date) // Schedule (overwrites existing)\nawait this.ctx.storage.getAlarm(): number | null // Get next alarm time\nawait this.ctx.storage.deleteAlarm(): void // Cancel alarm\n```\n\n**Limit:** 1 alarm per DO. Use queue pattern for multiple events (see [Patterns](./patterns.md)).\n\n## Storage APIs\n\nFor detailed storage documentation including SQLite queries, KV operations, transactions, and Point-in-Time Recovery, see **[DO Storage](../do-storage/README.md)**.\n\nQuick reference:\n\n```typescript\n// SQLite (recommended)\nthis.ctx.storage.sql.exec(\"SELECT * FROM users WHERE id = ?\", userId).one()\n\n// Sync KV (SQLite DOs only)\nthis.ctx.storage.kv.get(\"key\")\n\n// Async KV (legacy)\nawait this.ctx.storage.get(\"key\")\n```\n\n## Alarms\n\nSchedule future work that survives eviction:\n\n```typescript\n// Set alarm (overwrites any existing alarm)\nawait this.ctx.storage.setAlarm(Date.now() + 3600000) // 1 hour from now\nawait this.ctx.storage.setAlarm(new Date(\"2026-02-01\")) // Absolute time\n\n// Check next alarm\nconst nextRun = await this.ctx.storage.getAlarm() // null if none\n\n// Cancel alarm\nawait this.ctx.storage.deleteAlarm()\n\n// Handler called when alarm fires\nasync alarm() {\n // Runs once alarm triggers\n // DO wakes from hibernation if needed\n // Use for cleanup, notifications, scheduled tasks\n}\n```\n\n**Limitations:**\n- 1 alarm per DO maximum\n- Overwrites previous alarm when set\n- Use queue pattern for multiple scheduled events (see [Patterns](./patterns.md))\n\n**Reliability:**\n- Alarms survive DO eviction/restart\n- Cloudflare retries failed alarms automatically\n- Not guaranteed exactly-once (handle idempotently)\n\n## WebSocket Hibernation\n\nHibernation allows DOs with open WebSocket connections to consume zero compute/memory until message arrives.\n\n```typescript\nasync fetch(req: Request): Promise {\n const [client, server] = Object.values(new WebSocketPair());\n this.ctx.acceptWebSocket(server, [\"room:123\"]); // Tags for filtering\n server.serializeAttachment({ userId: \"abc\" }); // Persisted metadata\n return new Response(null, { status: 101, webSocket: client });\n}\n\n// Called when message arrives (DO wakes from hibernation)\nasync webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {\n const data = ws.deserializeAttachment(); // Retrieve metadata\n for (const c of this.ctx.getWebSockets(\"room:123\")) c.send(msg);\n}\n\n// Called on close (optional handler)\nasync webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {\n // Cleanup logic, remove from lists, etc.\n}\n\n// Called on error (optional handler)\nasync webSocketError(ws: WebSocket, error: unknown) {\n console.error(\"WebSocket error:\", error);\n // Handle error, close connection, etc.\n}\n```\n\n**Key concepts:**\n- **Auto-hibernation:** DO hibernates when no active requests/alarms\n- **Zero cost:** Hibernated DOs incur no charges while preserving connections\n- **Memory cleared:** All in-memory state lost on hibernation\n- **Attachment persistence:** Use `serializeAttachment()` for per-connection metadata that survives hibernation\n- **Tags for filtering:** Group connections by room/channel/user for targeted broadcasts\n\n**Handler lifecycle:**\n- `webSocketMessage`: DO wakes, processes message, may hibernate after\n- `webSocketClose`: Called when client closes (optional - implement for cleanup)\n- `webSocketError`: Called on connection error (optional - implement for error handling)\n\n**Metadata persistence:**\n```typescript\n// Store connection metadata (survives hibernation)\nws.serializeAttachment({ userId: \"abc\", room: \"lobby\" })\n\n// Retrieve after hibernation\nconst { userId, room } = ws.deserializeAttachment()\n```\n\n## See Also\n\n- **[DO Storage](../do-storage/README.md)** - Complete storage API reference\n- **[Patterns](./patterns.md)** - Real-world usage patterns\n- **[Gotchas](./gotchas.md)** - Hibernation caveats and limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/durable-objects/configuration.md", "content": "# Durable Objects Configuration\n\n## Basic Setup\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use latest; ≥2024-04-03 for RPC\n \"durable_objects\": {\n \"bindings\": [\n { \n \"name\": \"MY_DO\", // Env binding name\n \"class_name\": \"MyDO\" // Class exported from this worker\n },\n { \n \"name\": \"EXTERNAL\", // Access DO from another worker\n \"class_name\": \"ExternalDO\", \n \"script_name\": \"other-worker\"\n }\n ]\n },\n \"migrations\": [\n { \"tag\": \"v1\", \"new_sqlite_classes\": [\"MyDO\"] } // Prefer SQLite\n ]\n}\n```\n\n## Binding Options\n\n```jsonc\n{\n \"name\": \"BINDING_NAME\",\n \"class_name\": \"ClassName\",\n \"script_name\": \"other-worker\", // Optional: external DO\n \"environment\": \"production\" // Optional: isolate by env\n}\n```\n\n## Jurisdiction (Data Locality)\n\nSpecify jurisdiction at ID creation for data residency compliance:\n\n```typescript\n// EU data residency\nconst id = env.MY_DO.idFromName(\"user:123\", { jurisdiction: \"eu\" })\n\n// Available jurisdictions\nconst jurisdictions = [\"eu\", \"fedramp\"] // More may be added\n\n// All operations on this DO stay within jurisdiction\nconst stub = env.MY_DO.get(id)\nawait stub.someMethod() // Data stays in EU\n```\n\n**Key points:**\n- Set at ID creation time, immutable afterward\n- DO instance physically located within jurisdiction\n- Storage and compute guaranteed within boundary\n- Use for GDPR, FedRAMP, other compliance requirements\n- No cross-jurisdiction access (requests fail if DO in different jurisdiction)\n\n## Migrations\n\n```jsonc\n{\n \"migrations\": [\n { \"tag\": \"v1\", \"new_sqlite_classes\": [\"MyDO\"] }, // Create SQLite (recommended)\n // { \"tag\": \"v1\", \"new_classes\": [\"MyDO\"] }, // Create KV (paid only)\n { \"tag\": \"v2\", \"renamed_classes\": [{ \"from\": \"Old\", \"to\": \"New\" }] },\n { \"tag\": \"v3\", \"transferred_classes\": [{ \"from\": \"Src\", \"from_script\": \"old\", \"to\": \"Dest\" }] },\n { \"tag\": \"v4\", \"deleted_classes\": [\"Obsolete\"] } // Destroys ALL data!\n ]\n}\n```\n\n**Migration rules:**\n- Tags must be unique and sequential (v1, v2, v3...)\n- No rollback supported (test with `--dry-run` first)\n- Auto-applied on deploy\n- `new_sqlite_classes` recommended over `new_classes` (SQLite vs KV)\n- `deleted_classes` immediately destroys ALL data (irreversible)\n\n## Environment Isolation\n\nSeparate DO namespaces per environment (staging/production have distinct object instances):\n\n```jsonc\n{\n \"durable_objects\": {\n \"bindings\": [{ \"name\": \"MY_DO\", \"class_name\": \"MyDO\" }]\n },\n \"env\": {\n \"production\": {\n \"durable_objects\": {\n \"bindings\": [\n { \"name\": \"MY_DO\", \"class_name\": \"MyDO\", \"environment\": \"production\" }\n ]\n }\n }\n }\n}\n```\n\nDeploy: `npx wrangler deploy --env production`\n\n## Limits & Settings\n\n```jsonc\n{\n \"limits\": { \n \"cpu_ms\": 300000 // Max CPU time: 30s default, 300s max\n }\n}\n```\n\nSee [Gotchas](./gotchas.md) for complete limits table.\n\n## Types\n\n```typescript\nimport { DurableObject } from \"cloudflare:workers\";\n\ninterface Env {\n MY_DO: DurableObjectNamespace;\n}\n\nexport class MyDO extends DurableObject {}\n\ntype DurableObjectNamespace = {\n newUniqueId(options?: { jurisdiction?: string }): DurableObjectId;\n idFromName(name: string): DurableObjectId;\n idFromString(id: string): DurableObjectId;\n get(id: DurableObjectId): DurableObjectStub;\n};\n```\n\n## Commands\n\n```bash\n# Development\nnpx wrangler dev # Local dev\nnpx wrangler dev --remote # Test against production DOs\n\n# Deployment\nnpx wrangler deploy # Deploy + auto-apply migrations\nnpx wrangler deploy --dry-run # Validate migrations without deploying\nnpx wrangler deploy --env production\n\n# Management\nnpx wrangler durable-objects list # List namespaces\nnpx wrangler durable-objects info # Inspect specific DO\nnpx wrangler durable-objects delete # Delete DO (destroys data)\n```\n\n## See Also\n\n- **[API](./api.md)** - DurableObjectState and lifecycle handlers\n- **[Patterns](./patterns.md)** - Multi-environment patterns\n- **[Gotchas](./gotchas.md)** - Migration caveats, limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/durable-objects/gotchas.md", "content": "# Durable Objects Gotchas\n\n## Common Errors\n\n### \"Hibernation Cleared My In-Memory State\"\n\n**Problem:** Variables lost after hibernation \n**Cause:** DO auto-hibernates when idle; in-memory state not persisted \n**Solution:** Use `ctx.storage` for critical data, `ws.serializeAttachment()` for per-connection metadata\n\n```typescript\n// ❌ Wrong - lost on hibernation\nprivate userCount = 0;\nasync webSocketMessage(ws: WebSocket, msg: string) {\n this.userCount++; // Lost!\n}\n\n// ✅ Right - persisted\nasync webSocketMessage(ws: WebSocket, msg: string) {\n const count = this.ctx.storage.kv.get(\"userCount\") || 0;\n this.ctx.storage.kv.put(\"userCount\", count + 1);\n}\n```\n\n### \"setTimeout Didn't Fire After Restart\"\n\n**Problem:** Scheduled work lost on eviction \n**Cause:** `setTimeout` in-memory only; eviction clears timers \n**Solution:** Use `ctx.storage.setAlarm()` for reliable scheduling\n\n```typescript\n// ❌ Wrong - lost on eviction\nsetTimeout(() => this.cleanup(), 3600000);\n\n// ✅ Right - survives eviction\nawait this.ctx.storage.setAlarm(Date.now() + 3600000);\nasync alarm() { await this.cleanup(); }\n```\n\n### \"Constructor Runs on Every Wake\"\n\n**Problem:** Expensive init logic slows all requests \n**Cause:** Constructor runs on every wake (first request after eviction OR after hibernation) \n**Solution:** Lazy initialization or cache in storage\n\n**Critical understanding:** Constructor runs in two scenarios:\n1. **Cold start** - DO evicted from memory, first request creates new instance\n2. **Wake from hibernation** - DO with WebSockets hibernated, message/alarm wakes it\n\n```typescript\n// ❌ Wrong - expensive on every wake\nconstructor(ctx: DurableObjectState, env: Env) {\n super(ctx, env);\n this.heavyData = this.loadExpensiveData(); // Slow!\n}\n\n// ✅ Right - lazy load\nprivate heavyData?: HeavyData;\nprivate getHeavyData() {\n if (!this.heavyData) this.heavyData = this.loadExpensiveData();\n return this.heavyData;\n}\n```\n\n### \"Durable Object Overloaded (503 errors)\"\n\n**Problem:** 503 errors under load \n**Cause:** Single DO exceeding ~1K req/s throughput limit \n**Solution:** Shard across multiple DOs (see [Patterns: Sharding](./patterns.md))\n\n### \"Storage Quota Exceeded (Write failures)\"\n\n**Problem:** Write operations failing \n**Cause:** DO storage exceeding 10GB limit or account quota \n**Solution:** Cleanup with alarms, use `deleteAll()` for old data, upgrade plan\n\n### \"CPU Time Exceeded (Terminated)\"\n\n**Problem:** Request terminated mid-execution \n**Cause:** Processing exceeding 30s CPU time default limit \n**Solution:** Increase `limits.cpu_ms` in wrangler.jsonc (max 300s) or chunk work\n\n### \"WebSockets Disconnect on Eviction\"\n\n**Problem:** Connections drop unexpectedly \n**Cause:** DO evicted from memory without hibernation API \n**Solution:** Use WebSocket hibernation handlers + client reconnection logic\n\n### \"Migration Failed (Deploy error)\"\n\n**Cause:** Non-unique tags, non-sequential tags, or invalid class names in migration \n**Solution:** Check tag uniqueness/sequential ordering and verify class names are correct\n\n### \"RPC Method Not Found\"\n\n**Cause:** compatibility_date < 2024-04-03 preventing RPC usage \n**Solution:** Update compatibility_date to >= 2024-04-03 or use fetch() instead of RPC\n\n### \"Only One Alarm Allowed\"\n\n**Cause:** Need multiple scheduled tasks but only one alarm supported per DO \n**Solution:** Use event queue pattern to schedule multiple tasks with single alarm\n\n### \"Race Condition Despite Single-Threading\"\n\n**Problem:** Concurrent requests see inconsistent state \n**Cause:** Async operations allow request interleaving (await = yield point) \n**Solution:** Use `blockConcurrencyWhile()` for critical sections or atomic storage ops\n\n```typescript\n// ❌ Wrong - race condition\nasync incrementCounter() {\n const count = await this.ctx.storage.get(\"count\") || 0;\n // ⚠️ Another request could execute here during await\n await this.ctx.storage.put(\"count\", count + 1);\n}\n\n// ✅ Right - atomic operation\nasync incrementCounter() {\n return this.ctx.storage.sql.exec(\n \"INSERT INTO counters (id, value) VALUES (1, 1) ON CONFLICT(id) DO UPDATE SET value = value + 1 RETURNING value\"\n ).one().value;\n}\n\n// ✅ Right - explicit locking\nasync criticalOperation() {\n await this.ctx.blockConcurrencyWhile(async () => {\n const count = await this.ctx.storage.get(\"count\") || 0;\n await this.ctx.storage.put(\"count\", count + 1);\n });\n}\n```\n\n### \"Migration Rollback Not Supported\"\n\n**Cause:** Attempting to rollback a migration after deployment \n**Solution:** Test with `--dry-run` before deploying; migrations cannot be rolled back\n\n### \"deleted_classes Destroys Data\"\n\n**Problem:** Migration deleted all data \n**Cause:** `deleted_classes` migration immediately destroys all DO instances and data \n**Solution:** Test with `--dry-run`; use `transferred_classes` to preserve data during moves\n\n### \"Cold Starts Are Slow\"\n\n**Problem:** First request after eviction takes longer \n**Cause:** DO constructor + initial storage access on cold start \n**Solution:** Expected behavior; optimize constructor, use connection pooling in clients, consider warming strategy for critical DOs\n\n```typescript\n// Warming strategy (periodically ping critical DOs)\nexport default {\n async scheduled(event: ScheduledEvent, env: Env) {\n const criticalIds = [\"auth\", \"sessions\", \"locks\"];\n await Promise.all(criticalIds.map(name => {\n const id = env.MY_DO.idFromName(name);\n const stub = env.MY_DO.get(id);\n return stub.ping(); // Keep warm\n }));\n }\n};\n```\n\n## Limits\n\n| Limit | Free | Paid | Notes |\n|-------|------|------|-------|\n| SQLite storage per DO | 10 GB | 10 GB | Per Durable Object instance |\n| SQLite total storage | 5 GB | Unlimited | Account-wide quota |\n| Key+value size | 2 MB | 2 MB | Single KV pair (SQLite/async) |\n| CPU time default | 30s | 30s | Per request; configurable |\n| CPU time max | 300s | 300s | Set via `limits.cpu_ms` |\n| DO classes | 100 | 500 | Distinct DO class definitions |\n| SQL columns | 100 | 100 | Per table |\n| SQL statement size | 100 KB | 100 KB | Max SQL query size |\n| WebSocket message size | 32 MiB | 32 MiB | Per message |\n| Request throughput | ~1K req/s | ~1K req/s | Per DO (soft limit - shard for more) |\n| Alarms per DO | 1 | 1 | Use queue pattern for multiple events |\n| Total DOs | Unlimited | Unlimited | Create as many instances as needed |\n| WebSockets | Unlimited | Unlimited | Within 128MB memory limit per DO |\n| Memory per DO | 128 MB | 128 MB | In-memory state + WebSocket buffers |\n\n## Hibernation Caveats\n\n1. **Memory cleared** - All in-memory variables lost; reconstruct from storage or `deserializeAttachment()`\n2. **Constructor reruns** - Runs on wake; avoid expensive operations, use lazy initialization\n3. **No guarantees** - DO may evict instead of hibernate; design for both\n4. **Attachment limit** - `serializeAttachment()` data must be JSON-serializable, keep small\n5. **Alarm wakes DO** - Alarm prevents hibernation until handler completes\n6. **WebSocket state not automatic** - Must explicitly persist with `serializeAttachment()` or storage\n\n## See Also\n\n- **[Patterns](./patterns.md)** - Workarounds for common limitations\n- **[API](./api.md)** - Storage limits and quotas\n- **[Configuration](./configuration.md)** - Setting CPU limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/durable-objects/patterns.md", "content": "# Durable Objects Patterns\n\n## When to Use Which Pattern\n\n| Need | Pattern | ID Strategy |\n|------|---------|-------------|\n| Rate limit per user/IP | Rate Limiting | `idFromName(identifier)` |\n| Mutual exclusion | Distributed Lock | `idFromName(resource)` |\n| >1K req/s throughput | Sharding | `newUniqueId()` or hash |\n| Real-time updates | WebSocket Collab | `idFromName(room)` |\n| User sessions | Session Management | `idFromName(sessionId)` |\n| Background cleanup | Alarm-based | Any |\n\n## RPC vs fetch()\n\n**RPC** (compat ≥2024-04-03): Type-safe, simpler, default for new projects \n**fetch()**: Legacy compat, HTTP semantics, proxying\n\n```typescript\nconst count = await stub.increment(); // RPC\nconst count = await (await stub.fetch(req)).json(); // fetch()\n```\n\n## Sharding (High Throughput)\n\nSingle DO ~1K req/s max. Shard for higher throughput:\n\n```typescript\nexport default {\n async fetch(req: Request, env: Env): Promise {\n const userId = new URL(req.url).searchParams.get(\"user\");\n const hash = hashCode(userId) % 100; // 100 shards\n const id = env.COUNTER.idFromName(`shard:${hash}`);\n return env.COUNTER.get(id).fetch(req);\n }\n};\n\nfunction hashCode(str: string): number {\n let hash = 0;\n for (let i = 0; i < str.length; i++) hash = ((hash << 5) - hash) + str.charCodeAt(i);\n return Math.abs(hash);\n}\n```\n\n**Decisions:**\n- **Shard count**: 10-1000 typical (start with 100, measure, adjust)\n- **Shard key**: User ID, IP, session - must distribute evenly (use hash)\n- **Aggregation**: Coordinator DO or external system (D1, R2)\n\n## Rate Limiting\n\n```typescript\nasync checkLimit(key: string, limit: number, windowMs: number): Promise {\n const req = this.ctx.storage.sql.exec(\"SELECT COUNT(*) as count FROM requests WHERE key = ? AND timestamp > ?\", key, Date.now() - windowMs).one();\n if (req.count >= limit) return false;\n this.ctx.storage.sql.exec(\"INSERT INTO requests (key, timestamp) VALUES (?, ?)\", key, Date.now());\n return true;\n}\n```\n\n## Distributed Lock\n\n```typescript\nprivate held = false;\nasync acquire(timeoutMs = 5000): Promise {\n if (this.held) return false;\n this.held = true;\n await this.ctx.storage.setAlarm(Date.now() + timeoutMs);\n return true;\n}\nasync release() { this.held = false; await this.ctx.storage.deleteAlarm(); }\nasync alarm() { this.held = false; } // Auto-release on timeout\n```\n\n## Hibernation-Aware Pattern\n\nPreserve state across hibernation:\n\n```typescript\nasync fetch(req: Request): Promise {\n const [client, server] = Object.values(new WebSocketPair());\n const userId = new URL(req.url).searchParams.get(\"user\");\n server.serializeAttachment({ userId }); // Survives hibernation\n this.ctx.acceptWebSocket(server, [\"room:lobby\"]);\n server.send(JSON.stringify({ type: \"init\", state: this.ctx.storage.kv.get(\"state\") }));\n return new Response(null, { status: 101, webSocket: client });\n}\n\nasync webSocketMessage(ws: WebSocket, msg: string) {\n const { userId } = ws.deserializeAttachment(); // Retrieve after wake\n const state = this.ctx.storage.kv.get(\"state\") || {};\n state[userId] = JSON.parse(msg);\n this.ctx.storage.kv.put(\"state\", state);\n for (const c of this.ctx.getWebSockets(\"room:lobby\")) c.send(msg);\n}\n```\n\n## Real-time Collaboration\n\nBroadcast updates to all connected clients:\n\n```typescript\nasync webSocketMessage(ws: WebSocket, msg: string) {\n const data = JSON.parse(msg);\n this.ctx.storage.kv.put(\"doc\", data.content); // Persist\n for (const c of this.ctx.getWebSockets()) if (c !== ws) c.send(msg); // Broadcast\n}\n```\n\n### WebSocket Reconnection\n\n**Client-side** (exponential backoff):\n```typescript\nclass ResilientWS {\n private delay = 1000;\n connect(url: string) {\n const ws = new WebSocket(url);\n ws.onclose = () => setTimeout(() => {\n this.connect(url);\n this.delay = Math.min(this.delay * 2, 30000);\n }, this.delay);\n }\n}\n```\n\n**Server-side** (cleanup on close):\n```typescript\nasync webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {\n const { userId } = ws.deserializeAttachment();\n this.ctx.storage.sql.exec(\"UPDATE users SET online = false WHERE id = ?\", userId);\n for (const c of this.ctx.getWebSockets()) c.send(JSON.stringify({ type: \"user_left\", userId }));\n}\n```\n\n## Session Management\n\n```typescript\nasync createSession(userId: string, data: object): Promise {\n const id = crypto.randomUUID(), exp = Date.now() + 86400000;\n this.ctx.storage.sql.exec(\"INSERT INTO sessions VALUES (?, ?, ?, ?)\", id, userId, JSON.stringify(data), exp);\n await this.ctx.storage.setAlarm(exp);\n return id;\n}\n\nasync getSession(id: string): Promise {\n const row = this.ctx.storage.sql.exec(\"SELECT data FROM sessions WHERE id = ? AND expires_at > ?\", id, Date.now()).one();\n return row ? JSON.parse(row.data) : null;\n}\n\nasync alarm() { this.ctx.storage.sql.exec(\"DELETE FROM sessions WHERE expires_at <= ?\", Date.now()); }\n```\n\n## Multiple Events (Single Alarm)\n\nQueue pattern to schedule multiple events:\n\n```typescript\nasync scheduleEvent(id: string, runAt: number) {\n await this.ctx.storage.put(`event:${id}`, { id, runAt });\n const curr = await this.ctx.storage.getAlarm();\n if (!curr || runAt < curr) await this.ctx.storage.setAlarm(runAt);\n}\n\nasync alarm() {\n const events = await this.ctx.storage.list({ prefix: \"event:\" }), now = Date.now();\n let next = null;\n for (const [key, ev] of events) {\n if (ev.runAt <= now) {\n await this.processEvent(ev);\n await this.ctx.storage.delete(key);\n } else if (!next || ev.runAt < next) next = ev.runAt;\n }\n if (next) await this.ctx.storage.setAlarm(next);\n}\n```\n\n## Graceful Cleanup\n\nUse `ctx.waitUntil()` to complete work after response:\n\n```typescript\nasync myMethod() {\n const response = { success: true };\n this.ctx.waitUntil(this.ctx.storage.sql.exec(\"DELETE FROM old_data WHERE timestamp < ?\", cutoff));\n return response;\n}\n```\n\n## Best Practices\n\n- **Design**: Use `idFromName()` for coordination, `newUniqueId()` for sharding, minimize constructor work\n- **Storage**: Prefer SQLite, batch with transactions, set alarms for cleanup, use PITR before risky ops\n- **Performance**: ~1K req/s per DO max - shard for more, cache in memory, use alarms for deferred work\n- **Reliability**: Handle 503 with retry+backoff, design for cold starts, test migrations with `--dry-run`\n- **Security**: Validate inputs in Workers, rate limit DO creation, use jurisdiction for compliance\n\n## See Also\n\n- **[API](./api.md)** - ctx methods, WebSocket handlers\n- **[Gotchas](./gotchas.md)** - Hibernation caveats, common errors\n- **[DO Storage](../do-storage/README.md)** - Storage patterns and transactions\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-routing/README.md", "content": "# Cloudflare Email Routing Skill Reference\n\n## Overview\n\nCloudflare Email Routing enables custom email addresses for your domain that route to verified destination addresses. It's free, privacy-focused (no storage/access), and includes Email Workers for programmatic email processing.\n\n**Available to all Cloudflare customers using Cloudflare as authoritative nameserver.**\n\n## Quick Start\n\n```typescript\n// Basic email handler\nexport default {\n async email(message, env, ctx) {\n // CRITICAL: Must consume stream before response\n const parser = new PostalMime.default();\n const email = await parser.parse(await message.raw.arrayBuffer());\n \n // Process email\n console.log(`From: ${message.from}, Subject: ${email.subject}`);\n \n // Forward or reject\n await message.forward(\"verified@destination.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## Reading Order\n\n**Start here based on your goal:**\n\n1. **New to Email Routing?** → [configuration.md](configuration.md) → [patterns.md](patterns.md)\n2. **Adding Workers?** → [api.md](api.md) § Worker Runtime API → [patterns.md](patterns.md)\n3. **Sending emails?** → [api.md](api.md) § SendEmail Binding\n4. **Managing via API?** → [api.md](api.md) § REST API Operations\n5. **Debugging issues?** → [gotchas.md](gotchas.md)\n\n## Decision Tree\n\n```\nNeed to receive emails?\n├─ Simple forwarding only? → Dashboard rules (configuration.md)\n├─ Complex logic/filtering? → Email Workers (api.md + patterns.md)\n└─ Parse attachments/body? → postal-mime library (patterns.md § Parse Email)\n\nNeed to send emails?\n├─ From Worker? → SendEmail binding (api.md § SendEmail)\n└─ From external app? → Use external SMTP/API service\n\nHaving issues?\n├─ Email not arriving? → gotchas.md § Mail Authentication\n├─ Worker crashing? → gotchas.md § Stream Consumption\n└─ Forward failing? → gotchas.md § Destination Verification\n```\n\n## Key Concepts\n\n**Routing Rules**: Pattern-based forwarding configured via Dashboard/API. Simple but limited.\n\n**Email Workers**: Custom TypeScript handlers with full email access. Handles complex logic, parsing, storage, rejection.\n\n**SendEmail Binding**: Outbound email API for Workers. Transactional email only (no marketing/bulk).\n\n**ForwardableEmailMessage**: Runtime interface for incoming emails. Provides headers, raw stream, forward/reject methods.\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, wrangler config\n- **[api.md](api.md)** - REST API + Worker runtime API + types\n- **[patterns.md](patterns.md)** - Common patterns with working examples\n- **[gotchas.md](gotchas.md)** - Critical pitfalls, troubleshooting, limits\n\n## Architecture\n\n```\nInternet → MX Records → Cloudflare Email Routing\n ├─ Routing Rules (dashboard)\n └─ Email Worker (your code)\n ├─ Forward to destination\n ├─ Reject with reason\n ├─ Store in R2/KV/D1\n └─ Send outbound (SendEmail)\n```\n\n## See Also\n\n- [Cloudflare Docs: Email Routing](https://developers.cloudflare.com/email-routing/)\n- [Cloudflare Docs: Email Workers](https://developers.cloudflare.com/email-routing/email-workers/)\n- [postal-mime npm package](https://www.npmjs.com/package/postal-mime)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-routing/api.md", "content": "# Email Routing API Reference\n\n## Worker Runtime API\n\n### Email Handler Interface\n\n```typescript\ninterface ExportedHandler {\n email?(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): void | Promise;\n}\n```\n\n### ForwardableEmailMessage\n\nMain interface for incoming emails:\n\n```typescript\ninterface ForwardableEmailMessage {\n readonly from: string; // Envelope sender (e.g., \"sender@example.com\")\n readonly to: string; // Envelope recipient (e.g., \"you@yourdomain.com\")\n readonly headers: Headers; // Web API Headers object\n readonly raw: ReadableStream; // Raw MIME message stream\n \n setReject(reason: string): void;\n forward(rcptTo: string, headers?: Headers): Promise;\n}\n```\n\n**Key Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `from` | `string` | Envelope sender (MAIL FROM), not header From |\n| `to` | `string` | Envelope recipient (RCPT TO), not header To |\n| `headers` | `Headers` | Email headers (Subject, From, To, etc.) |\n| `raw` | `ReadableStream` | Raw MIME message (consume once only) |\n\n**Methods:**\n\n- `setReject(reason)`: Reject email with bounce message\n- `forward(rcptTo, headers?)`: Forward to verified destination, optionally add headers\n\n### Headers Object\n\nStandard Web API Headers interface:\n\n```typescript\n// Access headers\nconst subject = message.headers.get(\"subject\");\nconst from = message.headers.get(\"from\");\nconst messageId = message.headers.get(\"message-id\");\n\n// Check spam score\nconst spamScore = parseFloat(message.headers.get(\"x-cf-spamh-score\") || \"0\");\nif (spamScore > 5) {\n message.setReject(\"Spam detected\");\n}\n```\n\n### Common Headers\n\n`subject`, `from`, `to`, `x-cf-spamh-score` (spam score), `message-id` (deduplication), `dkim-signature` (auth)\n\n### Envelope vs Header Addresses\n\n**Critical distinction:**\n\n```typescript\n// Envelope addresses (routing, auth checks)\nmessage.from // \"bounce@sender.com\" (actual sender)\nmessage.to // \"you@yourdomain.com\" (your address)\n\n// Header addresses (display, user-facing)\nmessage.headers.get(\"from\") // \"Alice \"\nmessage.headers.get(\"to\") // \"Bob \"\n```\n\n**Use envelope addresses for:**\n- Authentication/SPF checks\n- Routing decisions\n- Bounce handling\n\n**Use header addresses for:**\n- Display to users\n- Reply-To logic\n- User-facing filtering\n\n## SendEmail Binding\n\nOutbound email API for transactional messages.\n\n### Configuration\n\n```jsonc\n// wrangler.jsonc\n{\n \"send_email\": [\n { \"name\": \"EMAIL\" }\n ]\n}\n```\n\n### TypeScript Types\n\n```typescript\ninterface Env {\n EMAIL: SendEmail;\n}\n\ninterface SendEmail {\n send(message: EmailMessage): Promise;\n}\n\ninterface EmailMessage {\n from: string | { name?: string; email: string };\n to: string | { name?: string; email: string } | Array;\n subject: string;\n text?: string;\n html?: string;\n headers?: Headers;\n reply_to?: string | { name?: string; email: string };\n}\n```\n\n### Send Email Example\n\n```typescript\ninterface Env {\n EMAIL: SendEmail;\n}\n\nexport default {\n async fetch(request, env, ctx): Promise {\n await env.EMAIL.send({\n from: { name: \"Acme Corp\", email: \"noreply@yourdomain.com\" },\n to: [\n { name: \"Alice\", email: \"alice@example.com\" },\n \"bob@example.com\"\n ],\n subject: \"Your order #12345 has shipped\",\n text: \"Track your package at: https://track.example.com/12345\",\n html: \"

Track your package at: View tracking

\",\n reply_to: { name: \"Support\", email: \"support@yourdomain.com\" }\n });\n \n return new Response(\"Email sent\");\n }\n} satisfies ExportedHandler;\n```\n\n### SendEmail Constraints\n\n- **From address**: Must be on verified domain (your domain with Email Routing enabled)\n- **Volume limits**: Transactional only, no bulk/marketing email\n- **Rate limits**: 100 emails/minute on Free plan, higher on Paid\n- **No attachments**: Use links to hosted files instead\n- **No DKIM control**: Cloudflare signs automatically\n\n## REST API Operations\n\nBase URL: `https://api.cloudflare.com/client/v4`\n\n### Authentication\n\n```bash\ncurl -H \"Authorization: Bearer $API_TOKEN\" https://api.cloudflare.com/client/v4/...\n```\n\n### Key Endpoints\n\n| Operation | Method | Endpoint |\n|-----------|--------|----------|\n| Enable routing | POST | `/zones/{zone_id}/email/routing/enable` |\n| Disable routing | POST | `/zones/{zone_id}/email/routing/disable` |\n| List rules | GET | `/zones/{zone_id}/email/routing/rules` |\n| Create rule | POST | `/zones/{zone_id}/email/routing/rules` |\n| Verify destination | POST | `/zones/{zone_id}/email/routing/addresses` |\n| List destinations | GET | `/zones/{zone_id}/email/routing/addresses` |\n\n### Create Routing Rule Example\n\n```bash\ncurl -X POST \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/rules\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"enabled\": true,\n \"name\": \"Forward sales\",\n \"matchers\": [{\"type\": \"literal\", \"field\": \"to\", \"value\": \"sales@yourdomain.com\"}],\n \"actions\": [{\"type\": \"forward\", \"value\": [\"alice@company.com\"]}],\n \"priority\": 0\n }'\n```\n\nMatcher types: `literal` (exact match), `all` (catch-all).\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-routing/configuration.md", "content": "# Email Routing Configuration\n\n## Wrangler Configuration\n\n### Basic Email Worker\n\n```jsonc\n// wrangler.jsonc\n{\n \"name\": \"email-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \"send_email\": [{ \"name\": \"EMAIL\" }]\n}\n```\n\n```typescript\n// src/index.ts\nexport default {\n async email(message, env, ctx) {\n await message.forward(\"destination@example.com\");\n }\n} satisfies ExportedHandler;\n```\n\n### With Storage Bindings\n\n```jsonc\n{\n \"name\": \"email-processor\",\n \"send_email\": [{ \"name\": \"EMAIL\" }],\n \"kv_namespaces\": [{ \"binding\": \"KV\", \"id\": \"abc123\" }],\n \"r2_buckets\": [{ \"binding\": \"R2\", \"bucket_name\": \"emails\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_id\": \"def456\" }]\n}\n```\n\n```typescript\ninterface Env {\n EMAIL: SendEmail;\n KV: KVNamespace;\n R2: R2Bucket;\n DB: D1Database;\n}\n```\n\n## Local Development\n\n```bash\nnpx wrangler dev\n\n# Test with curl\ncurl -X POST 'http://localhost:8787/__email' \\\n --header 'content-type: message/rfc822' \\\n --data 'From: test@example.com\nTo: you@yourdomain.com\nSubject: Test\n\nBody'\n```\n\n## Deployment\n\n```bash\nnpx wrangler deploy\n```\n\n**Connect to Email Routing:**\n\nDashboard: Email > Email Routing > [domain] > Settings > Email Workers > Select worker\n\nAPI:\n```bash\ncurl -X PUT \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/settings\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -d '{\"enabled\": true, \"worker\": \"email-worker\"}'\n```\n\n## DNS (Auto-Created)\n\n```dns\nyourdomain.com. IN MX 1 isaac.mx.cloudflare.net.\nyourdomain.com. IN MX 2 linda.mx.cloudflare.net.\nyourdomain.com. IN MX 3 amir.mx.cloudflare.net.\nyourdomain.com. IN TXT \"v=spf1 include:_spf.mx.cloudflare.net ~all\"\n```\n\n## Secrets & Variables\n\n```bash\n# Secrets (encrypted)\nnpx wrangler secret put API_KEY\n\n# Variables (plain)\n# wrangler.jsonc\n{ \"vars\": { \"THRESHOLD\": \"5.0\" } }\n```\n\n```typescript\ninterface Env {\n API_KEY: string;\n THRESHOLD: string;\n}\n```\n\n## TypeScript Setup\n\n```bash\nnpm install --save-dev @cloudflare/workers-types\n```\n\n```json\n// tsconfig.json\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"ES2022\",\n \"lib\": [\"ES2022\"],\n \"types\": [\"@cloudflare/workers-types\"],\n \"moduleResolution\": \"bundler\",\n \"strict\": true\n }\n}\n```\n\n```typescript\nimport type { ForwardableEmailMessage } from \"@cloudflare/workers-types\";\n\nexport default {\n async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise {\n await message.forward(\"dest@example.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## Dependencies\n\n```bash\nnpm install postal-mime\n```\n\n```typescript\nimport PostalMime from 'postal-mime';\n\nexport default {\n async email(message, env, ctx) {\n const parser = new PostalMime();\n const email = await parser.parse(await message.raw.arrayBuffer());\n console.log(email.subject);\n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## Multi-Environment\n\n```bash\n# wrangler.dev.jsonc\n{ \"name\": \"worker-dev\", \"vars\": { \"ENV\": \"dev\" } }\n\n# wrangler.prod.jsonc\n{ \"name\": \"worker-prod\", \"vars\": { \"ENV\": \"prod\" } }\n\nnpx wrangler deploy --config wrangler.dev.jsonc\nnpx wrangler deploy --config wrangler.prod.jsonc\n```\n\n## CI/CD (GitHub Actions)\n\n```yaml\n# .github/workflows/deploy.yml\nname: Deploy\non:\n push:\n branches: [main]\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npx wrangler deploy\n env:\n CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-routing/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Critical Pitfalls\n\n### Stream Consumption (MOST COMMON)\n\n**Problem:** \"stream already consumed\" or worker hangs\n\n**Cause:** `message.raw` is `ReadableStream` - consume once only\n\n**Solution:**\n```typescript\n// ❌ WRONG\nconst email1 = await parser.parse(await message.raw.arrayBuffer());\nconst email2 = await parser.parse(await message.raw.arrayBuffer()); // FAILS\n\n// ✅ CORRECT\nconst raw = await message.raw.arrayBuffer();\nconst email = await parser.parse(raw);\n```\n\nConsume `message.raw` immediately before any async operations.\n\n### Destination Verification\n\n**Problem:** Emails not forwarding\n\n**Cause:** Destination unverified\n\n**Solution:** Add destination, check inbox for verification email, click link. Verify status: `GET /zones/{id}/email/routing/addresses`\n\n### Mail Authentication\n\n**Problem:** Legitimate emails rejected\n\n**Cause:** Missing SPF/DKIM/DMARC on sender domain\n\n**Solution:** Configure sender DNS:\n```dns\nexample.com. IN TXT \"v=spf1 include:_spf.example.com ~all\"\nselector._domainkey.example.com. IN TXT \"v=DKIM1; k=rsa; p=...\"\n_dmarc.example.com. IN TXT \"v=DMARC1; p=quarantine\"\n```\n\n### Envelope vs Header\n\n**Problem:** Filtering on wrong address\n\n**Solution:**\n```typescript\n// Routing/auth: envelope\nif (message.from === \"trusted@example.com\") { }\n\n// Display: headers\nconst display = message.headers.get(\"from\");\n```\n\n### SendEmail Limits\n\n| Issue | Limit | Solution |\n|-------|-------|----------|\n| From domain | Must own | Use Email Routing domain |\n| Volume | ~100/min Free | Upgrade or throttle |\n| Attachments | Not supported | Link to R2 |\n| Type | Transactional | No bulk |\n\n## Common Errors\n\n### CPU Time Exceeded\n\n**Cause:** Heavy parsing, large emails\n\n**Solution:**\n```typescript\nconst size = parseInt(message.headers.get(\"content-length\") || \"0\") / 1024 / 1024;\nif (size > 20) {\n message.setReject(\"Too large\");\n return;\n}\n\nctx.waitUntil(expensiveWork());\nawait message.forward(\"dest@example.com\");\n```\n\n### Rule Not Triggering\n\n**Causes:** Priority conflict, matcher error, catch-all override\n\n**Solution:** Check priority (lower=first), verify exact match, confirm destination verified\n\n### Undefined Property\n\n**Cause:** Missing header\n\n**Solution:**\n```typescript\n// ❌ WRONG\nconst subj = message.headers.get(\"subject\").toLowerCase();\n\n// ✅ CORRECT\nconst subj = message.headers.get(\"subject\")?.toLowerCase() || \"\";\n```\n\n## Limits\n\n| Resource | Free | Paid |\n|----------|------|------|\n| Email size | 25 MB | 25 MB |\n| Rules | 200 | 200 |\n| Destinations | 200 | 200 |\n| CPU time | 10ms | 50ms |\n| SendEmail | ~100/min | Higher |\n\n## Debugging\n\n### Local\n\n```bash\nnpx wrangler dev\n\ncurl -X POST 'http://localhost:8787/__email' \\\n --header 'content-type: message/rfc822' \\\n --data 'From: test@example.com\nTo: you@yourdomain.com\nSubject: Test\n\nBody'\n```\n\n### Production\n\n```bash\nnpx wrangler tail\n```\n\n### Pattern\n\n```typescript\nexport default {\n async email(message, env, ctx) {\n try {\n console.log(\"From:\", message.from);\n await process(message, env);\n } catch (err) {\n console.error(err);\n message.setReject(err.message);\n }\n }\n} satisfies ExportedHandler;\n```\n\n## Auth Troubleshooting\n\n### Check Status\n\n```typescript\nconst auth = message.headers.get(\"authentication-results\") || \"\";\nconsole.log({\n spf: auth.includes(\"spf=pass\"),\n dkim: auth.includes(\"dkim=pass\"),\n dmarc: auth.includes(\"dmarc=pass\")\n});\n\nif (!auth.includes(\"pass\")) {\n message.setReject(\"Failed auth\");\n return;\n}\n```\n\n### SPF Issues\n\n**Causes:** Forwarding breaks SPF, too many lookups (>10), missing includes\n\n**Solution:**\n```dns\n; ✅ Good\nexample.com. IN TXT \"v=spf1 include:_spf.google.com ~all\"\n\n; ❌ Bad - too many\nexample.com. IN TXT \"v=spf1 include:a.com include:b.com ... ~all\"\n```\n\n### DMARC Alignment\n\n**Cause:** From domain must match SPF/DKIM domain\n\n## Best Practices\n\n1. Consume `message.raw` immediately\n2. Verify destinations\n3. Handle missing headers (`?.`)\n4. Use envelope for routing\n5. Check spam scores\n6. Test locally first\n7. Use `ctx.waitUntil` for background work\n8. Size-check early\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-routing/patterns.md", "content": "# Common Patterns\n\n## 1. Allowlist/Blocklist\n\n```typescript\n// Allowlist\nconst allowed = [\"user@example.com\", \"trusted@corp.com\"];\nif (!allowed.includes(message.from)) {\n message.setReject(\"Not allowed\");\n return;\n}\nawait message.forward(\"inbox@corp.com\");\n```\n\n## 2. Parse Email Body\n\n```typescript\nimport PostalMime from 'postal-mime';\n\nexport default {\n async email(message, env, ctx) {\n // CRITICAL: Consume stream immediately\n const raw = await message.raw.arrayBuffer();\n \n const parser = new PostalMime();\n const email = await parser.parse(raw);\n \n console.log({\n subject: email.subject,\n text: email.text,\n html: email.html,\n from: email.from.address,\n attachments: email.attachments.length\n });\n \n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 3. Spam Filter\n\n```typescript\nconst score = parseFloat(message.headers.get(\"x-cf-spamh-score\") || \"0\");\nif (score > 5) {\n message.setReject(\"Spam detected\");\n return;\n}\nawait message.forward(\"inbox@corp.com\");\n```\n\n## 4. Archive to R2\n\n```typescript\ninterface Env { R2: R2Bucket; }\n\nexport default {\n async email(message, env, ctx) {\n const raw = await message.raw.arrayBuffer();\n \n const key = `${new Date().toISOString()}-${message.from}.eml`;\n await env.R2.put(key, raw, { \n httpMetadata: { contentType: \"message/rfc822\" }\n });\n \n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 5. Store Metadata in KV\n\n```typescript\nimport PostalMime from 'postal-mime';\n\ninterface Env { KV: KVNamespace; }\n\nexport default {\n async email(message, env, ctx) {\n const raw = await message.raw.arrayBuffer();\n const parser = new PostalMime();\n const email = await parser.parse(raw);\n \n const metadata = {\n from: email.from.address,\n subject: email.subject,\n timestamp: new Date().toISOString(),\n size: raw.byteLength\n };\n \n await env.KV.put(`email:${Date.now()}`, JSON.stringify(metadata));\n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 6. Subject-Based Routing\n\n```typescript\nexport default {\n async email(message, env, ctx) {\n const subject = message.headers.get(\"subject\")?.toLowerCase() || \"\";\n \n if (subject.includes(\"[urgent]\")) {\n await message.forward(\"oncall@corp.com\");\n } else if (subject.includes(\"[billing]\")) {\n await message.forward(\"billing@corp.com\");\n } else if (subject.includes(\"[support]\")) {\n await message.forward(\"support@corp.com\");\n } else {\n await message.forward(\"general@corp.com\");\n }\n }\n} satisfies ExportedHandler;\n```\n\n## 7. Auto-Reply\n\n```typescript\ninterface Env {\n EMAIL: SendEmail;\n REPLIED: KVNamespace;\n}\n\nexport default {\n async email(message, env, ctx) {\n const msgId = message.headers.get(\"message-id\");\n \n if (msgId && await env.REPLIED.get(msgId)) {\n await message.forward(\"archive@corp.com\");\n return;\n }\n \n ctx.waitUntil((async () => {\n await env.EMAIL.send({\n from: \"noreply@yourdomain.com\",\n to: message.from,\n subject: \"Re: \" + (message.headers.get(\"subject\") || \"\"),\n text: \"Thank you. We'll respond within 24h.\"\n });\n if (msgId) await env.REPLIED.put(msgId, \"1\", { expirationTtl: 604800 });\n })());\n \n await message.forward(\"support@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 8. Extract Attachments\n\n```typescript\nimport PostalMime from 'postal-mime';\n\ninterface Env { ATTACHMENTS: R2Bucket; }\n\nexport default {\n async email(message, env, ctx) {\n const parser = new PostalMime();\n const email = await parser.parse(await message.raw.arrayBuffer());\n \n for (const att of email.attachments) {\n const key = `${Date.now()}-${att.filename}`;\n await env.ATTACHMENTS.put(key, att.content, {\n httpMetadata: { contentType: att.mimeType }\n });\n }\n \n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 9. Log to D1\n\n```typescript\nimport PostalMime from 'postal-mime';\n\ninterface Env { DB: D1Database; }\n\nexport default {\n async email(message, env, ctx) {\n const parser = new PostalMime();\n const email = await parser.parse(await message.raw.arrayBuffer());\n \n ctx.waitUntil(\n env.DB.prepare(\"INSERT INTO log (ts, from_addr, subj) VALUES (?, ?, ?)\")\n .bind(new Date().toISOString(), email.from.address, email.subject || \"\")\n .run()\n );\n \n await message.forward(\"inbox@corp.com\");\n }\n} satisfies ExportedHandler;\n```\n\n## 10. Multi-Tenant\n\n```typescript\ninterface Env { TENANTS: KVNamespace; }\n\nexport default {\n async email(message, env, ctx) {\n const subdomain = message.to.split(\"@\")[1].split(\".\")[0];\n const config = await env.TENANTS.get(subdomain, \"json\") as { forward: string } | null;\n \n if (!config) {\n message.setReject(\"Unknown tenant\");\n return;\n }\n \n await message.forward(config.forward);\n }\n} satisfies ExportedHandler;\n```\n\n## Summary\n\n| Pattern | Use Case | Storage |\n|---------|----------|---------|\n| Allowlist | Security | None |\n| Parse | Body/attachments | None |\n| Spam Filter | Reduce spam | None |\n| R2 Archive | Email storage | R2 |\n| KV Meta | Analytics | KV |\n| Subject Route | Dept routing | None |\n| Auto-Reply | Support | KV |\n| Attachments | Doc mgmt | R2 |\n| D1 Log | Audit trail | D1 |\n| Multi-Tenant | SaaS | KV |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-workers/README.md", "content": "# Cloudflare Email Workers\n\nProcess incoming emails programmatically using Cloudflare Workers runtime.\n\n## Overview\n\nEmail Workers enable custom email processing logic at the edge. Build spam filters, auto-responders, ticket systems, notification handlers, and more using the same Workers runtime you use for HTTP requests.\n\n**Key capabilities**:\n- Process inbound emails with full message access\n- Forward to verified destinations\n- Send replies with proper threading\n- Parse MIME content and attachments\n- Integrate with KV, R2, D1, and external APIs\n\n## Quick Start\n\n### Minimal ES Modules Handler\n\n```typescript\nexport default {\n async email(message, env, ctx) {\n // Reject spam\n if (message.from.includes('spam.com')) {\n message.setReject('Blocked');\n return;\n }\n \n // Forward to inbox\n await message.forward('inbox@example.com');\n }\n};\n```\n\n### Core Operations\n\n| Operation | Method | Use Case |\n|-----------|--------|----------|\n| Forward | `message.forward(to, headers?)` | Route to verified destination |\n| Reject | `message.setReject(reason)` | Block with SMTP error |\n| Reply | `message.reply(emailMessage)` | Auto-respond with threading |\n| Parse | postal-mime library | Extract subject, body, attachments |\n\n## Reading Order\n\nFor comprehensive understanding, read files in this order:\n\n1. **README.md** (this file) - Overview and quick start\n2. **configuration.md** - Setup, deployment, bindings\n3. **api.md** - Complete API reference\n4. **patterns.md** - Real-world implementation examples\n5. **gotchas.md** - Critical pitfalls and debugging\n\n## In This Reference\n\n| File | Description | Key Topics |\n|------|-------------|------------|\n| [api.md](./api.md) | Complete API reference | ForwardableEmailMessage, SendEmail bindings, reply() method, postal-mime/mimetext APIs |\n| [configuration.md](./configuration.md) | Setup and configuration | wrangler.jsonc, bindings, deployment, dependencies |\n| [patterns.md](./patterns.md) | Real-world examples | Allowlists from KV, auto-reply with threading, attachment extraction, webhook notifications |\n| [gotchas.md](./gotchas.md) | Pitfalls and debugging | Stream consumption, ctx.waitUntil errors, security, limits |\n\n## Architecture\n\n```\nIncoming Email → Email Routing → Email Worker\n ↓\n Process + Decide\n ↓\n ┌───────────────┼───────────────┐\n ↓ ↓ ↓\n Forward Reply Reject\n```\n\n**Event flow**:\n1. Email arrives at your domain\n2. Email Routing matches route (e.g., `support@example.com`)\n3. Bound Email Worker receives `ForwardableEmailMessage`\n4. Worker processes and takes action (forward/reply/reject)\n5. Email delivered or rejected based on worker logic\n\n## Key Concepts\n\n### Envelope vs Headers\n\n- **Envelope addresses** (`message.from`, `message.to`): SMTP transport addresses (trusted)\n- **Header addresses** (parsed from body): Display addresses (can be spoofed)\n\nUse envelope addresses for security decisions.\n\n### Single-Use Streams\n\n`message.raw` is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.\n\n```typescript\n// Buffer first\nconst buffer = await new Response(message.raw).arrayBuffer();\nconst email = await PostalMime.parse(buffer);\n```\n\nSee [gotchas.md](./gotchas.md#readablestream-can-only-be-consumed-once) for details.\n\n### Verified Destinations\n\n`forward()` only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.\n\n## Use Cases\n\n- **Spam filtering**: Block based on sender, content, or reputation\n- **Auto-responders**: Send acknowledgment replies with threading\n- **Ticket creation**: Parse emails and create support tickets\n- **Email archival**: Store in KV, R2, or D1\n- **Notification routing**: Forward to Slack, Discord, or webhooks\n- **Attachment processing**: Extract files to R2 storage\n- **Multi-tenant routing**: Route based on recipient subdomain\n- **Size filtering**: Reject oversized attachments\n\n## Limits\n\n| Limit | Value |\n|-------|-------|\n| Max message size | 25 MiB |\n| Max routing rules | 200 |\n| Max destinations | 200 |\n| CPU time (free tier) | 10ms |\n| CPU time (paid tier) | 50ms |\n\nSee [gotchas.md](./gotchas.md#limits-reference) for complete limits table.\n\n## Prerequisites\n\nBefore deploying Email Workers:\n\n1. **Enable Email Routing** in Cloudflare dashboard for your domain\n2. **Verify destination addresses** for forwarding\n3. **Configure DMARC/SPF** for sending domains (required for replies)\n4. **Set up wrangler.jsonc** with SendEmail binding\n\nSee [configuration.md](./configuration.md) for detailed setup.\n\n## Service Worker Syntax (Deprecated)\n\nModern projects should use ES modules format shown above. Service Worker syntax (`addEventListener('email', ...)`) is deprecated but still supported.\n\n## See Also\n\n- [Email Routing Documentation](https://developers.cloudflare.com/email-routing/)\n- [Workers Platform](https://developers.cloudflare.com/workers/)\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)\n- [postal-mime on npm](https://www.npmjs.com/package/postal-mime)\n- [mimetext on npm](https://www.npmjs.com/package/mimetext)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-workers/api.md", "content": "# Email Workers API Reference\n\nComplete API reference for Cloudflare Email Workers runtime.\n\n## ForwardableEmailMessage Interface\n\nThe main interface passed to email handlers.\n\n```typescript\ninterface ForwardableEmailMessage {\n readonly from: string; // Envelope MAIL FROM (SMTP sender)\n readonly to: string; // Envelope RCPT TO (SMTP recipient)\n readonly headers: Headers; // Web-standard Headers object\n readonly raw: ReadableStream; // Raw MIME message (single-use stream)\n readonly rawSize: number; // Total message size in bytes\n \n setReject(reason: string): void;\n forward(rcptTo: string, headers?: Headers): Promise;\n reply(message: EmailMessage): Promise;\n}\n```\n\n### Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `from` | string | Envelope sender (SMTP MAIL FROM) - use for security |\n| `to` | string | Envelope recipient (SMTP RCPT TO) |\n| `headers` | Headers | Message headers (Subject, Message-ID, etc.) |\n| `raw` | ReadableStream | Raw MIME message (**single-use**, buffer first) |\n| `rawSize` | number | Message size in bytes |\n\n### Methods\n\n#### setReject(reason: string): void\n\nReject with permanent SMTP 5xx error. Email not delivered, sender may receive bounce.\n\n```typescript\nif (blockList.includes(message.from)) {\n message.setReject('Sender blocked');\n}\n```\n\n#### forward(rcptTo: string, headers?: Headers): Promise\n\nForward to verified destination. Only `X-*` custom headers allowed.\n\n```typescript\nawait message.forward('inbox@example.com');\n\n// With custom headers\nconst h = new Headers();\nh.set('X-Processed-By', 'worker');\nawait message.forward('inbox@example.com', h);\n```\n\n#### reply(message: EmailMessage): Promise\n\nSend a reply to the original sender (March 2025 feature).\n\n```typescript\nimport { EmailMessage } from 'cloudflare:email';\nimport { createMimeMessage } from 'mimetext';\n\nconst msg = createMimeMessage();\nmsg.setSender({ name: 'Support', addr: 'support@example.com' });\nmsg.setRecipient(message.from);\nmsg.setSubject(`Re: ${message.headers.get('Subject')}`);\nmsg.setHeader('In-Reply-To', message.headers.get('Message-ID'));\nmsg.setHeader('References', message.headers.get('References') || '');\nmsg.addMessage({\n contentType: 'text/plain',\n data: 'Thank you for your message.'\n});\n\nawait message.reply(new EmailMessage(\n 'support@example.com',\n message.from,\n msg.asRaw()\n));\n```\n\n**Requirements**:\n- Incoming email needs valid DMARC\n- Reply once per event, recipient = `message.from`\n- Sender domain = receiving domain, with DMARC/SPF/DKIM\n- Max 100 `References` entries\n- Threading: `In-Reply-To` (original Message-ID), `References`, new `Message-ID`\n\n## EmailMessage Constructor\n\n```typescript\nimport { EmailMessage } from 'cloudflare:email';\n\nnew EmailMessage(from: string, to: string, raw: ReadableStream | string)\n```\n\nUsed for sending emails (replies or via SendEmail binding). Domain must be verified.\n\n## SendEmail Interface\n\n```typescript\ninterface SendEmail {\n send(message: EmailMessage): Promise;\n}\n\n// Usage\nawait env.EMAIL.send(new EmailMessage(from, to, mimeContent));\n```\n\n## SendEmail Binding Types\n\n```jsonc\n{\n \"send_email\": [\n { \"name\": \"EMAIL\" }, // Type 1: Any verified address\n { \"name\": \"LOGS\", \"destination_address\": \"logs@example.com\" }, // Type 2: Single dest\n { \"name\": \"TEAM\", \"allowed_destination_addresses\": [\"a@ex.com\", \"b@ex.com\"] }, // Type 3: Dest allowlist\n { \"name\": \"NOREPLY\", \"allowed_sender_addresses\": [\"noreply@ex.com\"] } // Type 4: Sender allowlist\n ]\n}\n```\n\n## postal-mime Parsed Output\n\npostal-mime v2.7.3 parses incoming emails into structured data.\n\n```typescript\ninterface ParsedEmail {\n headers: Array<{ key: string; value: string }>;\n from: { name: string; address: string } | null;\n to: Array<{ name: string; address: string }> | { name: string; address: string } | null;\n cc: Array<{ name: string; address: string }> | null;\n bcc: Array<{ name: string; address: string }> | null;\n subject: string;\n messageId: string | null;\n inReplyTo: string | null;\n references: string | null;\n date: string | null;\n html: string | null;\n text: string | null;\n attachments: Array<{\n filename: string;\n mimeType: string;\n disposition: string | null;\n related: boolean;\n contentId: string | null;\n content: Uint8Array;\n }>;\n}\n```\n\n### Usage\n\n```typescript\nimport PostalMime from 'postal-mime';\n\nconst buffer = await new Response(message.raw).arrayBuffer();\nconst email = await PostalMime.parse(buffer);\n\nconsole.log(email.subject);\nconsole.log(email.from?.address);\nconsole.log(email.text);\nconsole.log(email.attachments.length);\n```\n\n## mimetext API Quick Reference\n\nmimetext v3.0.27 composes outgoing emails.\n\n```typescript\nimport { createMimeMessage } from 'mimetext';\n\nconst msg = createMimeMessage();\n\n// Sender\nmsg.setSender({ name: 'John Doe', addr: 'john@example.com' });\n\n// Recipients\nmsg.setRecipient('alice@example.com');\nmsg.setRecipients(['bob@example.com', 'carol@example.com']);\nmsg.setCc('manager@example.com');\nmsg.setBcc(['audit@example.com']);\n\n// Headers\nmsg.setSubject('Meeting Notes');\nmsg.setHeader('In-Reply-To', '');\nmsg.setHeader('References', ' ');\nmsg.setHeader('Message-ID', `<${crypto.randomUUID()}@example.com>`);\n\n// Content\nmsg.addMessage({\n contentType: 'text/plain',\n data: 'Plain text content'\n});\n\nmsg.addMessage({\n contentType: 'text/html',\n data: '

HTML content

'\n});\n\n// Attachments\nmsg.addAttachment({\n filename: 'report.pdf',\n contentType: 'application/pdf',\n data: pdfBuffer // Uint8Array or base64 string\n});\n\n// Generate raw MIME\nconst raw = msg.asRaw(); // Returns string\n```\n\n## TypeScript Types\n\n```typescript\nimport { \n ForwardableEmailMessage,\n EmailMessage \n} from 'cloudflare:email';\n\ninterface Env {\n EMAIL: SendEmail;\n EMAIL_ARCHIVE: KVNamespace;\n ALLOWED_SENDERS: KVNamespace;\n}\n\nexport default {\n async email(\n message: ForwardableEmailMessage,\n env: Env,\n ctx: ExecutionContext\n ): Promise {\n // Fully typed\n }\n};\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-workers/configuration.md", "content": "# Email Workers Configuration\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"name\": \"email-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-27\",\n \"send_email\": [\n { \"name\": \"EMAIL\" }, // Unrestricted\n { \"name\": \"EMAIL_LOGS\", \"destination_address\": \"logs@example.com\" }, // Single dest\n { \"name\": \"EMAIL_TEAM\", \"allowed_destination_addresses\": [\"a@ex.com\", \"b@ex.com\"] },\n { \"name\": \"EMAIL_NOREPLY\", \"allowed_sender_addresses\": [\"noreply@ex.com\"] }\n ],\n \"kv_namespaces\": [{ \"binding\": \"ARCHIVE\", \"id\": \"xxx\" }],\n \"r2_buckets\": [{ \"binding\": \"ATTACHMENTS\", \"bucket_name\": \"email-attachments\" }],\n \"vars\": { \"WEBHOOK_URL\": \"https://hooks.example.com\" }\n}\n```\n\n## TypeScript Types\n\n```typescript\ninterface Env {\n EMAIL: SendEmail;\n ARCHIVE: KVNamespace;\n ATTACHMENTS: R2Bucket;\n WEBHOOK_URL: string;\n}\n\nexport default {\n async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {}\n};\n```\n\n## Dependencies\n\n```bash\nnpm install postal-mime mimetext\nnpm install -D @cloudflare/workers-types wrangler typescript\n```\n\nUse postal-mime v2.x, mimetext v3.x.\n\n## tsconfig.json\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\", \"module\": \"ES2022\", \"lib\": [\"ES2022\"],\n \"types\": [\"@cloudflare/workers-types\"],\n \"moduleResolution\": \"bundler\", \"strict\": true\n }\n}\n```\n\n## Local Development\n\n```bash\nnpx wrangler dev\n\n# Test receiving\ncurl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \\\n --url-query 'from=sender@example.com' --url-query 'to=recipient@example.com' \\\n --header 'Content-Type: text/plain' --data-raw 'Subject: Test\\n\\nHello'\n```\n\nSent emails write to local `.eml` files.\n\n## Deployment Checklist\n\n- [ ] Enable Email Routing in dashboard\n- [ ] Verify destination addresses\n- [ ] Configure DMARC/SPF/DKIM for sending\n- [ ] Create KV/R2 resources if needed\n- [ ] Update wrangler.jsonc with production IDs\n\n```bash\nnpx wrangler deploy\nnpx wrangler deployments list\n```\n\n## Dashboard Setup\n\n1. **Email Routing:** Domain → Email → Enable Email Routing\n2. **Verify addresses:** Email → Destination addresses → Add & verify\n3. **Bind Worker:** Email → Email Workers → Create route → Select pattern & Worker\n4. **DMARC:** Add TXT `_dmarc.domain.com`: `v=DMARC1; p=quarantine;`\n\n## Secrets\n\n```bash\nnpx wrangler secret put API_KEY\n# Access: env.API_KEY\n```\n\n## Monitoring\n\n```bash\nnpx wrangler tail\nnpx wrangler tail --status error\nnpx wrangler tail --format json\n```\n\n## Troubleshooting\n\n| Error | Fix |\n|-------|-----|\n| \"Binding not found\" | Check `send_email` name matches code |\n| \"Invalid destination\" | Verify in Email Routing dashboard |\n| Type errors | Install `@cloudflare/workers-types` |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-workers/gotchas.md", "content": "# Email Workers Gotchas\n\n## Critical Issues\n\n### ReadableStream Single-Use\n\n```typescript\n// ❌ WRONG: Stream consumed twice\nconst email = await PostalMime.parse(await new Response(message.raw).arrayBuffer());\nconst rawText = await new Response(message.raw).text(); // EMPTY!\n\n// ✅ CORRECT: Buffer first\nconst buffer = await new Response(message.raw).arrayBuffer();\nconst email = await PostalMime.parse(buffer);\nconst rawText = new TextDecoder().decode(buffer);\n```\n\n### ctx.waitUntil() Errors Silent\n\n```typescript\n// ❌ Errors dropped silently\nctx.waitUntil(fetch(webhookUrl, { method: 'POST', body: data }));\n\n// ✅ Catch and log\nctx.waitUntil(\n fetch(webhookUrl, { method: 'POST', body: data })\n .catch(err => env.ERROR_LOG.put(`error:${Date.now()}`, err.message))\n);\n```\n\n## Security\n\n### Envelope vs Header From (Spoofing)\n\n```typescript\nconst envelopeFrom = message.from; // SMTP MAIL FROM (trusted)\nconst headerFrom = (await PostalMime.parse(buffer)).from?.address; // (untrusted)\n// Use envelope for security decisions\n```\n\n### Input Validation\n\n```typescript\nif (message.rawSize > 5_000_000) { message.setReject('Too large'); return; }\nif ((message.headers.get('Subject') || '').length > 1000) {\n message.setReject('Invalid subject'); return;\n}\n```\n\n### DMARC for Replies\n\nReplies fail silently without DMARC. Verify: `dig TXT _dmarc.example.com`\n\n## Parsing\n\n### Address Parsing\n\n```typescript\nconst email = await PostalMime.parse(buffer);\nconst fromAddress = email.from?.address || 'unknown';\nconst toAddresses = Array.isArray(email.to) ? email.to.map(t => t.address) : [email.to?.address];\n```\n\n### Character Encoding\n\nLet postal-mime handle decoding - `email.subject`, `email.text`, `email.html` are UTF-8.\n\n## API Behavior\n\n### setReject() vs throw\n\n```typescript\n// setReject() for SMTP rejection\nif (blockList.includes(message.from)) { message.setReject('Blocked'); return; }\n\n// throw for worker errors\nif (!env.KV) throw new Error('KV not configured');\n```\n\n### forward() Only X-* Headers\n\n```typescript\nheaders.set('X-Processed-By', 'worker'); // ✅ Works\nheaders.set('Subject', 'Modified'); // ❌ Dropped\n```\n\n### Reply Requires Verified Domain\n\n```typescript\n// Use same domain as receiving address\nconst receivingDomain = message.to.split('@')[1];\nawait message.reply(new EmailMessage(`noreply@${receivingDomain}`, message.from, rawMime));\n```\n\n## Performance\n\n### CPU Limit\n\n```typescript\n// Skip parsing large emails\nif (message.rawSize > 5_000_000) {\n await message.forward('inbox@example.com');\n return;\n}\n```\n\nMonitor: `npx wrangler tail`\n\n## Limits\n\n| Limit | Value |\n|-------|-------|\n| Max message size | 25 MiB |\n| Max rules/zone | 200 |\n| CPU time (free/paid) | 10ms / 50ms |\n| Reply References | 100 |\n\n## Common Errors\n\n| Error | Fix |\n|-------|-----|\n| \"Address not verified\" | Add in Email Routing dashboard |\n| \"Exceeded CPU time\" | Use `ctx.waitUntil()` or upgrade |\n| \"Stream is locked\" | Buffer `message.raw` first |\n| Silent reply failure | Check DMARC records |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/email-workers/patterns.md", "content": "# Email Workers Patterns\n\n## Parse Email\n\n```typescript\nimport PostalMime from 'postal-mime';\n\nexport default {\n async email(message, env, ctx) {\n const buffer = await new Response(message.raw).arrayBuffer();\n const email = await PostalMime.parse(buffer);\n console.log(email.from, email.subject, email.text, email.attachments.length);\n await message.forward('inbox@example.com');\n }\n};\n```\n\n## Filtering\n\n```typescript\n// Allowlist from KV\nconst allowList = await env.ALLOWED_SENDERS.get('list', 'json') || [];\nif (!allowList.includes(message.from)) {\n message.setReject('Not allowed');\n return;\n}\n\n// Size check (avoid parsing large emails)\nif (message.rawSize > 5_000_000) {\n await message.forward('inbox@example.com'); // Forward without parsing\n return;\n}\n```\n\n## Auto-Reply with Threading\n\n```typescript\nimport { EmailMessage } from 'cloudflare:email';\nimport { createMimeMessage } from 'mimetext';\n\nconst msg = createMimeMessage();\nmsg.setSender({ addr: 'support@example.com' });\nmsg.setRecipient(message.from);\nmsg.setSubject(`Re: ${message.headers.get('Subject')}`);\nmsg.setHeader('In-Reply-To', message.headers.get('Message-ID') || '');\nmsg.addMessage({ contentType: 'text/plain', data: 'Thank you. We will respond.' });\n\nawait message.reply(new EmailMessage('support@example.com', message.from, msg.asRaw()));\n```\n\n## Rate-Limited Auto-Reply\n\n```typescript\nconst rateKey = `rate:${message.from}`;\nif (!await env.RATE_LIMIT.get(rateKey)) {\n // Send reply...\n ctx.waitUntil(env.RATE_LIMIT.put(rateKey, '1', { expirationTtl: 3600 }));\n}\n```\n\n## Subject-Based Routing\n\n```typescript\nconst subject = (message.headers.get('Subject') || '').toLowerCase();\nif (subject.includes('billing')) await message.forward('billing@example.com');\nelse if (subject.includes('support')) await message.forward('support@example.com');\nelse await message.forward('general@example.com');\n```\n\n## Multi-Tenant Routing\n\n```typescript\n// support+tenant123@example.com → tenant123\nconst tenantId = message.to.split('@')[0].match(/\\+(.+)$/)?.[1] || 'default';\nconst config = await env.TENANT_CONFIG.get(tenantId, 'json');\nconfig?.forwardTo ? await message.forward(config.forwardTo) : message.setReject('Unknown');\n```\n\n## Archive & Extract Attachments\n\n```typescript\n// Archive to KV\nctx.waitUntil(env.ARCHIVE.put(`email:${Date.now()}`, JSON.stringify({\n from: message.from, subject: email.subject\n})));\n\n// Attachments to R2\nfor (const att of email.attachments) {\n ctx.waitUntil(env.R2.put(`${Date.now()}-${att.filename}`, att.content));\n}\n```\n\n## Webhook Integration\n\n```typescript\nctx.waitUntil(\n fetch(env.WEBHOOK_URL, {\n method: 'POST',\n body: JSON.stringify({ from: message.from, subject: message.headers.get('Subject') })\n }).catch(err => console.error(err))\n);\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/hyperdrive/README.md", "content": "# Hyperdrive\n\nAccelerates database queries from Workers via connection pooling, edge setup, query caching.\n\n## Key Features\n\n- **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)\n- **Edge Setup**: Connection negotiation at edge, pooling near origin\n- **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)\n- **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)\n\n## Architecture\n\n```\nWorker → Edge (setup) → Pool (near DB) → Origin\n ↓ cached reads\n Cache\n```\n\n## Quick Start\n\n```bash\n# Create config\nnpx wrangler hyperdrive create my-db \\\n --connection-string=\"postgres://user:pass@host:5432/db\"\n\n# wrangler.jsonc\n{\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"hyperdrive\": [{\"binding\": \"HYPERDRIVE\", \"id\": \"\"}]\n}\n```\n\n```typescript\nimport { Client } from \"pg\";\n\nexport default {\n async fetch(req: Request, env: Env): Promise {\n const client = new Client({\n connectionString: env.HYPERDRIVE.connectionString,\n });\n await client.connect();\n const result = await client.query(\"SELECT * FROM users WHERE id = $1\", [123]);\n await client.end();\n return Response.json(result.rows);\n },\n};\n```\n\n## When to Use\n\n✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads\n❌ Write-heavy, real-time data (<1s), single-region apps close to DB\n\n**💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.\n\n## Driver Choice\n\n| Driver | Use When | Notes |\n|--------|----------|-------|\n| **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs |\n| **postgres.js** | Advanced features, template literals, streaming | Lighter than pg, `prepare: true` is default |\n| **mysql2** | MySQL/MariaDB/PlanetScale | MySQL only, less mature support |\n\n## Reading Order\n\n| New to Hyperdrive | Implementing | Troubleshooting |\n|-------------------|--------------|-----------------|\n| 1. README (this) | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md) |\n| 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md) | 2. [patterns.md](./patterns.md) |\n| 3. [api.md](./api.md) | 3. [patterns.md](./patterns.md) | 3. [api.md](./api.md) |\n\n## In This Reference\n- [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement\n- [api.md](./api.md) - Binding APIs, query patterns, driver usage\n- [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization\n- [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management\n\n## See Also\n- [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases\n- [d1](../d1/) - Serverless SQLite alternative for edge-native apps\n- [workers](../workers/) - Worker runtime with database bindings\n" }, { "path": "skills/.curated/cloudflare-deploy/references/hyperdrive/api.md", "content": "# API Reference\n\nSee [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.\n\n## Binding Interface\n\n```typescript\ninterface Hyperdrive {\n connectionString: string; // PostgreSQL\n // MySQL properties:\n host: string;\n port: number;\n user: string;\n password: string;\n database: string;\n}\n\ninterface Env {\n HYPERDRIVE: Hyperdrive;\n}\n```\n\n**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)\n\n## PostgreSQL (node-postgres) - RECOMMENDED\n\n```typescript\nimport { Client } from \"pg\"; // pg@^8.17.2\n\nexport default {\n async fetch(req: Request, env: Env): Promise {\n const client = new Client({connectionString: env.HYPERDRIVE.connectionString});\n try {\n await client.connect();\n const result = await client.query(\"SELECT * FROM users WHERE id = $1\", [123]);\n return Response.json(result.rows);\n } finally {\n await client.end();\n }\n },\n};\n```\n\n**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.\n\n## PostgreSQL (postgres.js)\n\n```typescript\nimport postgres from \"postgres\"; // postgres@^3.4.8\n\nconst sql = postgres(env.HYPERDRIVE.connectionString, {\n max: 5, // Limit per Worker (Workers max: 6)\n prepare: true, // Enabled by default, required for caching\n fetch_types: false, // Reduce latency if not using arrays\n});\n\nconst users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`;\n```\n\n**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.\n\n## MySQL (mysql2)\n\n```typescript\nimport { createConnection } from \"mysql2/promise\"; // mysql2@^3.16.2\n\nconst conn = await createConnection({\n host: env.HYPERDRIVE.host,\n user: env.HYPERDRIVE.user,\n password: env.HYPERDRIVE.password,\n database: env.HYPERDRIVE.database,\n port: env.HYPERDRIVE.port,\n disableEval: true, // ⚠️ REQUIRED for Workers\n});\n\nconst [results] = await conn.query(\"SELECT * FROM users WHERE active = ? LIMIT ?\", [true, 10]);\nctx.waitUntil(conn.end());\n```\n\n**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.\n\n## Query Caching\n\n**Cacheable:**\n```sql\nSELECT * FROM posts WHERE published = true;\nSELECT COUNT(*) FROM users;\n```\n\n**NOT cacheable:**\n```sql\n-- Writes\nINSERT/UPDATE/DELETE\n\n-- Volatile functions\nSELECT NOW();\nSELECT random();\nSELECT LASTVAL(); -- PostgreSQL\nSELECT UUID(); -- MySQL\n```\n\n**Cache config:**\n- Default: `max_age=60s`, `swr=15s`\n- Max `max_age`: 3600s\n- Disable: `--caching-disabled=true`\n\n**Multiple configs pattern:**\n```typescript\n// Reads: cached\nconst sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString);\nconst posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`;\n\n// Writes/time-sensitive: no cache\nconst sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString);\nconst orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`;\n```\n\n## ORMs\n\n**Drizzle:**\n```typescript\nimport { drizzle } from \"drizzle-orm/postgres-js\"; // drizzle-orm@^0.45.1\nimport postgres from \"postgres\";\n\nconst client = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});\nconst db = drizzle(client);\nconst users = await db.select().from(users).where(eq(users.active, true)).limit(10);\n```\n\n**Kysely:**\n```typescript\nimport { Kysely, PostgresDialect } from \"kysely\"; // kysely@^0.27+\nimport postgres from \"postgres\";\n\nconst db = new Kysely({\n dialect: new PostgresDialect({\n postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}),\n }),\n});\nconst users = await db.selectFrom(\"users\").selectAll().where(\"active\", \"=\", true).execute();\n```\n\nSee [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/hyperdrive/configuration.md", "content": "# Configuration\n\nSee [README.md](./README.md) for overview.\n\n## Create Config\n\n**PostgreSQL:**\n```bash\n# Basic\nnpx wrangler hyperdrive create my-db \\\n --connection-string=\"postgres://user:pass@host:5432/db\"\n\n# Custom cache\nnpx wrangler hyperdrive create my-db \\\n --connection-string=\"postgres://...\" \\\n --max-age=120 --swr=30\n\n# No cache\nnpx wrangler hyperdrive create my-db \\\n --connection-string=\"postgres://...\" \\\n --caching-disabled=true\n```\n\n**MySQL:**\n```bash\nnpx wrangler hyperdrive create my-db \\\n --connection-string=\"mysql://user:pass@host:3306/db\"\n```\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"compatibility_date\": \"2025-01-01\", // Use latest for new projects\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"hyperdrive\": [\n {\n \"binding\": \"HYPERDRIVE\",\n \"id\": \"\",\n \"localConnectionString\": \"postgres://user:pass@localhost:5432/dev\"\n }\n ]\n}\n```\n\n**Generate TypeScript types:** Run `npx wrangler types` to auto-generate `worker-configuration.d.ts` from your wrangler.jsonc.\n\n**Multiple configs:**\n```jsonc\n{\n \"hyperdrive\": [\n {\"binding\": \"HYPERDRIVE_CACHED\", \"id\": \"\"},\n {\"binding\": \"HYPERDRIVE_NO_CACHE\", \"id\": \"\"}\n ]\n}\n```\n\n## Management\n\n```bash\nnpx wrangler hyperdrive list\nnpx wrangler hyperdrive get \nnpx wrangler hyperdrive update --max-age=180\nnpx wrangler hyperdrive delete \n```\n\n## Config Options\n\nHyperdrive create/update CLI flags:\n\n| Option | Default | Notes |\n|--------|---------|-------|\n| `--caching-disabled` | `false` | Disable caching |\n| `--max-age` | `60` | Cache TTL (max 3600s) |\n| `--swr` | `15` | Stale-while-revalidate |\n| `--origin-connection-limit` | 20/100 | Free/paid |\n| `--access-client-id` | - | Tunnel auth |\n| `--access-client-secret` | - | Tunnel auth |\n| `--sslmode` | `require` | PostgreSQL only |\n\n## Smart Placement Integration\n\nFor Workers making **multiple queries** per request, enable Smart Placement to execute near your database:\n\n```jsonc\n{\n \"compatibility_date\": \"2025-01-01\",\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"placement\": {\n \"mode\": \"smart\"\n },\n \"hyperdrive\": [\n {\n \"binding\": \"HYPERDRIVE\",\n \"id\": \"\"\n }\n ]\n}\n```\n\n**Benefits:** Multi-query Workers run closer to DB, reducing round-trip latency. See [patterns.md](./patterns.md) for examples.\n\n## Private DB via Tunnel\n\n```\nWorker → Hyperdrive → Access → Tunnel → Private Network → DB\n```\n\n**Setup:**\n```bash\n# 1. Create tunnel\ncloudflared tunnel create my-db-tunnel\n\n# 2. Configure hostname in Zero Trust dashboard\n# Domain: db-tunnel.example.com\n# Service: TCP -> localhost:5432\n\n# 3. Create service token (Zero Trust > Service Auth)\n# Save Client ID/Secret\n\n# 4. Create Access app (db-tunnel.example.com)\n# Policy: Service Auth token from step 3\n\n# 5. Create Hyperdrive\nnpx wrangler hyperdrive create my-private-db \\\n --host=db-tunnel.example.com \\\n --user=dbuser --password=dbpass --database=prod \\\n --access-client-id= --access-client-secret=\n```\n\n**⚠️ Don't specify `--port` with Tunnel** - port configured in tunnel service settings.\n\n## Local Dev\n\n**Option 1: Local (RECOMMENDED):**\n```bash\n# Env var (takes precedence)\nexport CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=\"postgres://user:pass@localhost:5432/dev\"\nnpx wrangler dev\n\n# wrangler.jsonc\n{\"hyperdrive\": [{\"binding\": \"HYPERDRIVE\", \"localConnectionString\": \"postgres://...\"}]}\n```\n\n**Remote DB locally:**\n```bash\n# PostgreSQL\nexport CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=\"postgres://user:pass@remote:5432/db?sslmode=require\"\n\n# MySQL\nexport CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=\"mysql://user:pass@remote:3306/db?sslMode=REQUIRED\"\n```\n\n**Option 2: Remote execution:**\n```bash\nnpx wrangler dev --remote # Uses deployed config, affects production\n```\n\nSee [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md).\n" }, { "path": "skills/.curated/cloudflare-deploy/references/hyperdrive/gotchas.md", "content": "# Gotchas\n\nSee [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md).\n\n## Common Errors\n\n### \"Too many open connections\" / \"Connection limit exceeded\"\n\n**Cause:** Workers have a hard limit of **6 concurrent connections per invocation** \n**Solution:** Set `max: 5` in driver config, reuse connections, ensure proper cleanup with `client.end()` or `ctx.waitUntil(conn.end())`\n\n### \"Failed to acquire a connection (Pool exhausted)\"\n\n**Cause:** All connections in pool are in use, often due to long-running transactions \n**Solution:** Reduce transaction duration, avoid queries >60s, don't hold connections during external calls, or upgrade to paid plan for more connections\n\n### \"connection_refused\"\n\n**Cause:** Database refusing connections due to firewall, connection limits, or service down \n**Solution:** Check firewall allows Cloudflare IPs, verify DB listening on port, confirm service running, and validate credentials\n\n### \"Query timeout (deadline exceeded)\"\n\n**Cause:** Query execution exceeding 60s timeout limit \n**Solution:** Optimize with indexes, reduce dataset with LIMIT, break into smaller queries, or use async processing\n\n### \"password authentication failed\"\n\n**Cause:** Invalid credentials in Hyperdrive configuration \n**Solution:** Check username and password in Hyperdrive config match database credentials\n\n### \"SSL/TLS connection error\"\n\n**Cause:** SSL/TLS configuration mismatch between Hyperdrive and database \n**Solution:** Add `sslmode=require` (Postgres) or `sslMode=REQUIRED` (MySQL), upload CA cert if self-signed, verify DB has SSL enabled, and check cert expiry\n\n### \"Queries not being cached\"\n\n**Cause:** Query is mutating (INSERT/UPDATE/DELETE), contains volatile functions (NOW(), RANDOM()), or caching disabled \n**Solution:** Verify query is non-mutating SELECT, avoid volatile functions, confirm caching enabled, use `wrangler dev --remote` to test, and set `prepare=true` for postgres.js\n\n### \"Slow multi-query Workers despite Hyperdrive\"\n\n**Cause:** Worker executing at edge, each query round-trips to DB region \n**Solution:** Enable Smart Placement (`\"placement\": {\"mode\": \"smart\"}` in wrangler.jsonc) to execute Worker near DB. See [patterns.md](./patterns.md) Multi-Query pattern.\n\n### \"Local database connection failed\"\n\n**Cause:** `localConnectionString` incorrect or database not running \n**Solution:** Verify `localConnectionString` correct, check DB running, confirm env var name matches binding, and test with psql/mysql client\n\n### \"Environment variable not working\"\n\n**Cause:** Environment variable format incorrect or not exported \n**Solution:** Use format `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_`, ensure binding matches wrangler.jsonc, export variable in shell, and restart wrangler dev\n\n## Limits\n\n| Limit | Free | Paid | Notes |\n|-------|------|------|-------|\n| Max configs | 10 | 25 | Hyperdrive configurations per account |\n| Worker connections | 6 | 6 | Max concurrent connections per Worker invocation |\n| Username/DB name | 63 bytes | 63 bytes | Maximum length |\n| Connection timeout | 15s | 15s | Time to establish connection |\n| Idle timeout | 10 min | 10 min | Connection idle timeout |\n| Max origin connections | ~20 | ~100 | Connections to origin database |\n| Query duration max | 60s | 60s | Queries >60s terminated |\n| Cached response max | 50 MB | 50 MB | Responses >50MB returned but not cached |\n\n## Resources\n\n- [Docs](https://developers.cloudflare.com/hyperdrive/)\n- [Getting Started](https://developers.cloudflare.com/hyperdrive/get-started/)\n- [Wrangler Reference](https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/)\n- [Supported DBs](https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/)\n- [Discord #hyperdrive](https://discord.cloudflare.com)\n- [Limit Increase Form](https://forms.gle/ukpeZVLWLnKeixDu7)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/hyperdrive/patterns.md", "content": "# Patterns\n\nSee [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md).\n\n## High-Traffic Read-Heavy\n\n```typescript\nconst sql = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});\n\n// Cacheable: popular content\nconst posts = await sql`SELECT * FROM posts WHERE published = true ORDER BY views DESC LIMIT 20`;\n\n// Cacheable: user profiles\nconst [user] = await sql`SELECT id, username, bio FROM users WHERE id = ${userId}`;\n```\n\n**Benefits:** Trending/profiles cached (60s), connection pooling handles spikes.\n\n## Mixed Read/Write\n\n```typescript\ninterface Env {\n HYPERDRIVE_CACHED: Hyperdrive; // max_age=120\n HYPERDRIVE_REALTIME: Hyperdrive; // caching disabled\n}\n\n// Reads: cached\nif (req.method === \"GET\") {\n const sql = postgres(env.HYPERDRIVE_CACHED.connectionString, {prepare: true});\n const products = await sql`SELECT * FROM products WHERE category = ${cat}`;\n}\n\n// Writes: no cache (immediate consistency)\nif (req.method === \"POST\") {\n const sql = postgres(env.HYPERDRIVE_REALTIME.connectionString, {prepare: true});\n await sql`INSERT INTO orders ${sql(data)}`;\n}\n```\n\n## Analytics Dashboard\n\n```typescript\nconst client = new Client({connectionString: env.HYPERDRIVE.connectionString});\nawait client.connect();\n\n// Aggregate queries cached (use fixed timestamps for caching)\nconst thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();\nconst dailyStats = await client.query(`\n SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue\n FROM orders WHERE created_at >= $1\n GROUP BY DATE(created_at) ORDER BY date DESC\n`, [thirtyDaysAgo]);\n\nconst sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();\nconst topProducts = await client.query(`\n SELECT p.name, COUNT(oi.id) as count, SUM(oi.quantity * oi.price) as revenue\n FROM order_items oi JOIN products p ON oi.product_id = p.id\n WHERE oi.created_at >= $1\n GROUP BY p.id, p.name ORDER BY revenue DESC LIMIT 10\n`, [sevenDaysAgo]);\n```\n\n**Benefits:** Expensive aggregations cached (avoid NOW() for cacheability), dashboard instant, reduced DB load.\n\n## Multi-Tenant\n\n```typescript\nconst tenantId = req.headers.get(\"X-Tenant-ID\");\nconst sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});\n\n// Tenant-scoped queries cached separately\nconst docs = await sql`\n SELECT * FROM documents \n WHERE tenant_id = ${tenantId} AND deleted_at IS NULL\n ORDER BY updated_at DESC LIMIT 50\n`;\n```\n\n**Benefits:** Per-tenant caching, shared connection pool, protects DB from multi-tenant load.\n\n## Geographically Distributed\n\n```typescript\n// Worker runs at edge nearest user\n// Connection setup at edge (fast), pooling near DB (efficient)\nconst sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});\nconst [user] = await sql`SELECT * FROM users WHERE id = ${userId}`;\n\nreturn Response.json({\n user,\n serverRegion: req.cf?.colo, // Edge location\n});\n```\n\n**Benefits:** Edge setup + DB pooling = global → single-region DB without replication.\n\n## Multi-Query + Smart Placement\n\nFor Workers making **multiple queries** per request, enable Smart Placement to execute near DB:\n\n```jsonc\n// wrangler.jsonc\n{\n \"placement\": {\"mode\": \"smart\"},\n \"hyperdrive\": [{\"binding\": \"HYPERDRIVE\", \"id\": \"\"}]\n}\n```\n\n```typescript\nconst sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});\n\n// Multiple queries benefit from Smart Placement\nconst [user] = await sql`SELECT * FROM users WHERE id = ${userId}`;\nconst orders = await sql`SELECT * FROM orders WHERE user_id = ${userId} ORDER BY created_at DESC LIMIT 10`;\nconst stats = await sql`SELECT COUNT(*) as total, SUM(amount) as spent FROM orders WHERE user_id = ${userId}`;\n\nreturn Response.json({user, orders, stats});\n```\n\n**Benefits:** Worker executes near DB → reduces latency for each query. Without Smart Placement, each query round-trips from edge.\n\n## Connection Pooling\n\nOperates in **transaction mode**: connection acquired per transaction, `RESET` on return.\n\n**SET statements:**\n```typescript\n// ✅ Within transaction\nawait client.query(\"BEGIN\");\nawait client.query(\"SET work_mem = '256MB'\");\nawait client.query(\"SELECT * FROM large_table\"); // Uses SET\nawait client.query(\"COMMIT\"); // RESET after\n\n// ✅ Single statement\nawait client.query(\"SET work_mem = '256MB'; SELECT * FROM large_table\");\n\n// ❌ Across queries (may get different connection)\nawait client.query(\"SET work_mem = '256MB'\");\nawait client.query(\"SELECT * FROM large_table\"); // SET not applied\n```\n\n**Best practices:**\n```typescript\n// ❌ Long transactions block pooling\nawait client.query(\"BEGIN\");\nawait processThousands(); // Connection held entire time\nawait client.query(\"COMMIT\");\n\n// ✅ Short transactions\nawait client.query(\"BEGIN\");\nawait client.query(\"UPDATE users SET status = $1 WHERE id = $2\", [status, id]);\nawait client.query(\"COMMIT\");\n\n// ✅ SET LOCAL within transaction\nawait client.query(\"BEGIN\");\nawait client.query(\"SET LOCAL work_mem = '256MB'\");\nawait client.query(\"SELECT * FROM large_table\");\nawait client.query(\"COMMIT\");\n```\n\n## Performance Tips\n\n**Enable prepared statements (required for caching):**\n```typescript\nconst sql = postgres(connectionString, {prepare: true}); // Default, enables caching\n```\n\n**Optimize connection settings:**\n```typescript\nconst sql = postgres(connectionString, {\n max: 5, // Stay under Workers' 6 connection limit\n fetch_types: false, // Reduce latency if not using arrays\n idle_timeout: 60, // Match Worker lifetime\n});\n```\n\n**Write cache-friendly queries:**\n```typescript\n// ✅ Cacheable (deterministic)\nawait sql`SELECT * FROM products WHERE category = 'electronics' LIMIT 10`;\n\n// ❌ Not cacheable (volatile NOW())\nawait sql`SELECT * FROM logs WHERE created_at > NOW()`;\n\n// ✅ Cacheable (parameterized timestamp)\nconst ts = Date.now();\nawait sql`SELECT * FROM logs WHERE created_at > ${ts}`;\n```\n\nSee [gotchas.md](./gotchas.md) for limits, troubleshooting.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/images/README.md", "content": "# Cloudflare Images Skill Reference\n\n**Cloudflare Images** is an end-to-end image management solution providing storage, transformation, optimization, and delivery at scale via Cloudflare's global network.\n\n## Quick Decision Tree\n\n**Need to:**\n- **Transform in Worker?** → [api.md](api.md#workers-binding-api-2026-primary-method) (Workers Binding API)\n- **Upload from Worker?** → [api.md](api.md#upload-from-worker) (REST API)\n- **Upload from client?** → [patterns.md](patterns.md#upload-from-client-direct-creator-upload) (Direct Creator Upload)\n- **Set up variants?** → [configuration.md](configuration.md#variants-configuration)\n- **Serve responsive images?** → [patterns.md](patterns.md#responsive-images)\n- **Add watermarks?** → [patterns.md](patterns.md#watermarking)\n- **Fix errors?** → [gotchas.md](gotchas.md#common-errors)\n\n## Reading Order\n\n**For building image upload/transform feature:**\n1. [configuration.md](configuration.md) - Setup Workers binding\n2. [api.md](api.md#workers-binding-api-2026-primary-method) - Learn transform API\n3. [patterns.md](patterns.md#upload-from-client-direct-creator-upload) - Direct upload pattern\n4. [gotchas.md](gotchas.md) - Check limits and errors\n\n**For URL-based transforms:**\n1. [configuration.md](configuration.md#variants-configuration) - Create variants\n2. [api.md](api.md#url-transform-api) - URL syntax\n3. [patterns.md](patterns.md#responsive-images) - Responsive patterns\n\n**For troubleshooting:**\n1. [gotchas.md](gotchas.md#common-errors) - Error messages\n2. [gotchas.md](gotchas.md#limits) - Size/format limits\n\n## Core Methods\n\n| Method | Use Case | Location |\n|--------|----------|----------|\n| `env.IMAGES.input().transform()` | Transform in Worker | [api.md:11](api.md) |\n| REST API `/images/v1` | Upload images | [api.md:57](api.md) |\n| Direct Creator Upload | Client-side upload | [api.md:127](api.md) |\n| URL transforms | Static image delivery | [api.md:112](api.md) |\n\n## In This Reference\n\n- **[api.md](api.md)** - Complete API: Workers binding, REST endpoints, URL transforms\n- **[configuration.md](configuration.md)** - Setup: wrangler.toml, variants, auth, signed URLs\n- **[patterns.md](patterns.md)** - Patterns: responsive images, watermarks, format negotiation, caching\n- **[gotchas.md](gotchas.md)** - Troubleshooting: limits, errors, best practices\n\n## Key Features\n\n- **Automatic Optimization** - AVIF/WebP format negotiation\n- **On-the-fly Transforms** - Resize, crop, blur, sharpen via URL or API\n- **Workers Binding** - Transform images in Workers (2026 primary method)\n- **Direct Upload** - Secure client-side uploads without backend proxy\n- **Global Delivery** - Cached at 300+ Cloudflare data centers\n- **Watermarking** - Overlay images programmatically\n\n## See Also\n\n- [Official Docs](https://developers.cloudflare.com/images/)\n- [Workers Examples](https://developers.cloudflare.com/images/tutorials/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/images/api.md", "content": "# API Reference\n\n## Workers Binding API\n\n```toml\n# wrangler.toml\n[images]\nbinding = \"IMAGES\"\n```\n\n### Transform Images\n\n```typescript\nconst imageResponse = await env.IMAGES\n .input(fileBuffer)\n .transform({ width: 800, height: 600, fit: \"cover\", quality: 85, format: \"avif\" })\n .output();\nreturn imageResponse.response();\n```\n\n### Transform Options\n\n```typescript\ninterface TransformOptions {\n width?: number; height?: number;\n fit?: \"scale-down\" | \"contain\" | \"cover\" | \"crop\" | \"pad\";\n quality?: number; // 1-100\n format?: \"avif\" | \"webp\" | \"jpeg\" | \"png\";\n dpr?: number; // 1-3\n gravity?: \"auto\" | \"left\" | \"right\" | \"top\" | \"bottom\" | \"face\" | string;\n sharpen?: number; // 0-10\n blur?: number; // 1-250\n rotate?: 90 | 180 | 270;\n background?: string; // CSS color for pad\n metadata?: \"none\" | \"copyright\" | \"keep\";\n brightness?: number; contrast?: number; gamma?: number; // 0-2\n}\n```\n\n### Draw/Watermark\n\n```typescript\nawait env.IMAGES.input(baseImage)\n .draw(env.IMAGES.input(watermark).transform({ width: 100 }), { top: 10, left: 10, opacity: 0.8 })\n .output();\n```\n\n## REST API\n\n### Upload Image\n\n```bash\ncurl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \\\n -H \"Authorization: Bearer {token}\" -F file=@image.jpg -F metadata='{\"key\":\"value\"}'\n```\n\n### Other Operations\n\n```bash\nGET /accounts/{account_id}/images/v1/{image_id} # Get details\nDELETE /accounts/{account_id}/images/v1/{image_id} # Delete\nGET /accounts/{account_id}/images/v1?page=1 # List\n```\n\n## URL Transform API\n\n```\nhttps://imagedelivery.net/{hash}/{id}/width=800,height=600,fit=cover,format=avif\n```\n\n**Params:** `w=`, `h=`, `fit=`, `q=`, `f=`, `dpr=`, `gravity=`, `sharpen=`, `blur=`, `rotate=`, `background=`, `metadata=`\n\n## Direct Creator Upload\n\n```typescript\n// 1. Get upload URL (backend)\nconst { result } = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v2/direct_upload`,\n { method: 'POST', headers: { 'Authorization': `Bearer ${token}` },\n body: JSON.stringify({ requireSignedURLs: false }) }\n).then(r => r.json());\n\n// 2. Client uploads to result.uploadURL\nconst formData = new FormData();\nformData.append('file', file);\nawait fetch(result.uploadURL, { method: 'POST', body: formData });\n```\n\n## Error Codes\n\n| Code | Message | Solution |\n|------|---------|----------|\n| 5400 | Invalid format | Use JPEG, PNG, GIF, WebP |\n| 5401 | Too large | Max 100MB |\n| 5403 | Invalid transform | Check params |\n| 9413 | Rate limit | Implement backoff |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/images/configuration.md", "content": "# Configuration\n\n## Wrangler Integration\n\n### Workers Binding Setup\n\nAdd to `wrangler.toml`:\n\n```toml\nname = \"my-image-worker\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2024-01-01\"\n\n[images]\nbinding = \"IMAGES\"\n```\n\nAccess in Worker:\n\n```typescript\ninterface Env {\n IMAGES: ImageBinding;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n return await env.IMAGES\n .input(imageBuffer)\n .transform({ width: 800 })\n .output()\n .response();\n }\n};\n```\n\n### Upload via Script\n\nWrangler doesn't have built-in Images commands, use REST API:\n\n```typescript\n// scripts/upload-image.ts\nimport fs from 'fs';\nimport FormData from 'form-data';\n\nasync function uploadImage(filePath: string) {\n const accountId = process.env.CLOUDFLARE_ACCOUNT_ID!;\n const apiToken = process.env.CLOUDFLARE_API_TOKEN!;\n \n const formData = new FormData();\n formData.append('file', fs.createReadStream(filePath));\n \n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v1`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${apiToken}`,\n },\n body: formData,\n }\n );\n \n const result = await response.json();\n console.log('Uploaded:', result);\n}\n\nuploadImage('./photo.jpg');\n```\n\n### Environment Variables\n\nStore account hash for URL construction:\n\n```toml\n[vars]\nIMAGES_ACCOUNT_HASH = \"your-account-hash\"\nACCOUNT_ID = \"your-account-id\"\n```\n\nAccess in Worker:\n\n```typescript\nconst imageUrl = `https://imagedelivery.net/${env.IMAGES_ACCOUNT_HASH}/${imageId}/public`;\n```\n\n## Variants Configuration\n\nVariants are named presets for transformations.\n\n### Create Variant (Dashboard)\n\n1. Navigate to Images → Variants\n2. Click \"Create Variant\"\n3. Set name (e.g., `thumbnail`)\n4. Configure: `width=200,height=200,fit=cover`\n\n### Create Variant (API)\n\n```bash\ncurl -X POST \\\n https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants \\\n -H \"Authorization: Bearer {api_token}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"id\": \"thumbnail\",\n \"options\": {\n \"width\": 200,\n \"height\": 200,\n \"fit\": \"cover\"\n },\n \"neverRequireSignedURLs\": true\n }'\n```\n\n### Use Variant\n\n```\nhttps://imagedelivery.net/{account_hash}/{image_id}/thumbnail\n```\n\n### Common Variant Presets\n\n```json\n{\n \"thumbnail\": {\n \"width\": 200,\n \"height\": 200,\n \"fit\": \"cover\"\n },\n \"avatar\": {\n \"width\": 128,\n \"height\": 128,\n \"fit\": \"cover\",\n \"gravity\": \"face\"\n },\n \"hero\": {\n \"width\": 1920,\n \"height\": 1080,\n \"fit\": \"cover\",\n \"quality\": 90\n },\n \"mobile\": {\n \"width\": 640,\n \"fit\": \"scale-down\",\n \"quality\": 80,\n \"format\": \"avif\"\n }\n}\n```\n\n## Authentication\n\n### API Token (Recommended)\n\nGenerate at: Dashboard → My Profile → API Tokens\n\nRequired permissions:\n- Account → Cloudflare Images → Edit\n\n```bash\ncurl -H \"Authorization: Bearer {api_token}\" \\\n https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1\n```\n\n### API Key (Legacy)\n\n```bash\ncurl -H \"X-Auth-Email: {email}\" \\\n -H \"X-Auth-Key: {api_key}\" \\\n https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1\n```\n\n## Signed URLs\n\nFor private images, enable signed URLs:\n\n```bash\n# Upload with signed URLs required\ncurl -X POST \\\n https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \\\n -H \"Authorization: Bearer {api_token}\" \\\n -F file=@private.jpg \\\n -F requireSignedURLs=true\n```\n\nGenerate signed URL:\n\n```typescript\nimport { createHmac } from 'crypto';\n\nfunction signUrl(imageId: string, variant: string, expiry: number, key: string): string {\n const path = `/${imageId}/${variant}`;\n const toSign = `${path}${expiry}`;\n const signature = createHmac('sha256', key)\n .update(toSign)\n .digest('hex');\n \n return `https://imagedelivery.net/{hash}${path}?exp=${expiry}&sig=${signature}`;\n}\n\n// Sign URL valid for 1 hour\nconst signedUrl = signUrl('image-id', 'public', Date.now() + 3600, env.SIGNING_KEY);\n```\n\n## Local Development\n\n```bash\nnpx wrangler dev --remote\n```\n\nMust use `--remote` for Images binding access.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/images/gotchas.md", "content": "# Gotchas & Best Practices\n\n## Fit Modes\n\n| Mode | Best For | Behavior |\n|------|----------|----------|\n| `cover` | Hero images, thumbnails | Fills space, crops excess |\n| `contain` | Product images, artwork | Preserves full image, may add padding |\n| `scale-down` | User uploads | Never enlarges |\n| `crop` | Precise crops | Uses gravity |\n| `pad` | Fixed aspect ratio | Adds background |\n\n## Format Selection\n\n```typescript\nformat: 'auto' // Recommended - negotiates best format\n```\n\n**Support:** AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)\n\n## Quality Settings\n\n| Use Case | Quality |\n|----------|---------|\n| Thumbnails | 75-80 |\n| Standard | 85 (default) |\n| High-quality | 90-95 |\n\n## Common Errors\n\n### 5403: \"Image transformation failed\"\n- Verify `width`/`height` ≤ 12000\n- Check `quality` 1-100, `dpr` 1-3\n- Don't combine incompatible options\n\n### 9413: \"Rate limit exceeded\"\nImplement caching and exponential backoff:\n```typescript\nfor (let i = 0; i < 3; i++) {\n try { return await env.IMAGES.input(buffer).transform({...}).output(); }\n catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }\n}\n```\n\n### 5401: \"Image too large\"\nPre-process images before upload (max 100MB, 12000×12000px)\n\n### 5400: \"Invalid image format\"\nSupported: JPEG, PNG, GIF, WebP, AVIF, SVG\n\n### 401/403: \"Unauthorized\"\nVerify API token has `Cloudflare Images → Edit` permission\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Max input size | 100MB |\n| Max dimensions | 12000×12000px |\n| Quality range | 1-100 |\n| DPR range | 1-3 |\n| API rate limit | ~1200 req/min |\n\n## AVIF Gotchas\n\n- **Slower encoding**: First request may have higher latency\n- **Browser detection**:\n```typescript\nconst format = /image\\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';\n```\n\n## Anti-Patterns\n\n```typescript\n// ❌ No caching - transforms every request\nreturn env.IMAGES.input(buffer).transform({...}).output().response();\n\n// ❌ cover without both dimensions\ntransform({ width: 800, fit: 'cover' })\n\n// ✅ Always set both for cover\ntransform({ width: 800, height: 600, fit: 'cover' })\n\n// ❌ Exposes API token to client\n// ✅ Use Direct Creator Upload (patterns.md)\n```\n\n## Debugging\n\n```typescript\n// Check response headers\nconsole.log('Content-Type:', response.headers.get('Content-Type'));\n\n// Test with curl\n// curl -I \"https://imagedelivery.net/{hash}/{id}/width=800,format=avif\"\n\n// Monitor logs\n// npx wrangler tail\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/images/patterns.md", "content": "# Common Patterns\n\n## URL Transform Options\n\n```\nwidth= height= fit=scale-down|contain|cover|crop|pad\nquality=85 format=auto|webp|avif|jpeg|png dpr=2\ngravity=auto|face|left|right|top|bottom sharpen=2 blur=10\nrotate=90|180|270 background=white metadata=none|copyright|keep\n```\n\n## Responsive Images (srcset)\n\n```html\n\n```\n\n## Format Negotiation\n\n```typescript\nasync fetch(request: Request, env: Env): Promise {\n const accept = request.headers.get('Accept') || '';\n const format = /image\\/avif/.test(accept) ? 'avif' : /image\\/webp/.test(accept) ? 'webp' : 'jpeg';\n return env.IMAGES.input(buffer).transform({ format, quality: 85 }).output().response();\n}\n```\n\n## Direct Creator Upload\n\n```typescript\n// Backend: Generate upload URL\nconst response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/images/v2/direct_upload`,\n { method: 'POST', headers: { 'Authorization': `Bearer ${env.API_TOKEN}` },\n body: JSON.stringify({ requireSignedURLs: false, metadata: { userId } }) }\n);\n\n// Frontend: Upload to returned uploadURL\nconst formData = new FormData();\nformData.append('file', file);\nawait fetch(result.uploadURL, { method: 'POST', body: formData });\n// Use: https://imagedelivery.net/{hash}/${result.id}/public\n```\n\n## Transform & Store to R2\n\n```typescript\nasync fetch(request: Request, env: Env): Promise {\n const file = (await request.formData()).get('image') as File;\n const transformed = await env.IMAGES\n .input(await file.arrayBuffer())\n .transform({ width: 800, format: 'avif', quality: 80 })\n .output();\n await env.R2.put(`images/${Date.now()}.avif`, transformed.response().body);\n return Response.json({ success: true });\n}\n```\n\n## Watermarking\n\n```typescript\nconst watermark = await env.ASSETS.fetch(new URL('/watermark.png', request.url));\nconst result = await env.IMAGES\n .input(await image.arrayBuffer())\n .draw(env.IMAGES.input(watermark.body).transform({ width: 100 }), { bottom: 20, right: 20, opacity: 0.7 })\n .transform({ format: 'avif' })\n .output();\nreturn result.response();\n```\n\n## Device-Based Transforms\n\n```typescript\nconst ua = request.headers.get('User-Agent') || '';\nconst isMobile = /Mobile|Android|iPhone/i.test(ua);\nreturn env.IMAGES.input(buffer)\n .transform({ width: isMobile ? 400 : 1200, quality: isMobile ? 75 : 85, format: 'avif' })\n .output().response();\n```\n\n## Caching Strategy\n\n```typescript\nasync fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const cache = caches.default;\n let response = await cache.match(request);\n if (!response) {\n response = await env.IMAGES.input(buffer).transform({ width: 800, format: 'avif' }).output().response();\n response = new Response(response.body, { headers: { ...response.headers, 'Cache-Control': 'public, max-age=86400' } });\n ctx.waitUntil(cache.put(request, response.clone()));\n }\n return response;\n}\n```\n\n## Batch Processing\n\n```typescript\nconst results = await Promise.all(images.map(buffer =>\n env.IMAGES.input(buffer).transform({ width: 800, fit: 'cover', format: 'avif' }).output()\n));\n```\n\n## Error Handling\n\n```typescript\ntry {\n return (await env.IMAGES.input(buffer).transform({ width: 800 }).output()).response();\n} catch (error) {\n console.error('Transform failed:', error);\n return new Response('Image processing failed', { status: 500 });\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/kv/README.md", "content": "# Cloudflare Workers KV\n\nGlobally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.\n\n## Overview\n\nKV provides:\n- Eventual consistency (60s global propagation)\n- Read-optimized performance\n- 25 MiB value limit per key\n- Auto-replication to Cloudflare edge\n- Metadata support (1024 bytes)\n\n**Use cases:** Config storage, user sessions, feature flags, caching, A/B testing\n\n## When to Use KV\n\n| Need | Recommendation |\n|------|----------------|\n| Strong consistency | → [Durable Objects](../durable-objects/) |\n| SQL queries | → [D1](../d1/) |\n| Object storage (files) | → [R2](../r2/) |\n| High read, low write volume | → KV ✅ |\n| Sub-10ms global reads | → KV ✅ |\n\n**Quick comparison:**\n\n| Feature | KV | D1 | Durable Objects |\n|---------|----|----|-----------------|\n| Consistency | Eventual | Strong | Strong |\n| Read latency | <10ms | ~50ms | <1ms |\n| Write limit | 1/s per key | Unlimited | Unlimited |\n| Use case | Config, cache | Relational data | Coordination |\n\n## Quick Start\n\n```bash\nwrangler kv namespace create MY_NAMESPACE\n# Add binding to wrangler.jsonc\n```\n\n```typescript\n// Write\nawait env.MY_KV.put(\"key\", \"value\", { expirationTtl: 300 });\n\n// Read\nconst value = await env.MY_KV.get(\"key\");\nconst json = await env.MY_KV.get(\"config\", \"json\");\n```\n\n## Core Operations\n\n| Method | Purpose | Returns |\n|--------|---------|---------|\n| `get(key, type?)` | Single read | `string \\| null` |\n| `get(keys, type?)` | Bulk read (≤100) | `Map` |\n| `put(key, value, options?)` | Write | `Promise` |\n| `delete(key)` | Delete | `Promise` |\n| `list(options?)` | List keys | `{ keys, list_complete, cursor? }` |\n| `getWithMetadata(key)` | Get + metadata | `{ value, metadata }` |\n\n## Consistency Model\n\n- **Write visibility:** Immediate in same location, ≤60s globally\n- **Read path:** Eventually consistent\n- **Write rate:** 1 write/second per key (429 on exceed)\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| Quick start | README → configuration.md |\n| Implement feature | README → api.md → patterns.md |\n| Debug issues | gotchas.md → api.md |\n| Batch operations | api.md (bulk section) → patterns.md |\n| Performance tuning | gotchas.md (performance) → patterns.md (caching) |\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, namespace creation, TypeScript types\n- [api.md](./api.md) - KV methods, bulk operations, cacheTtl, content types\n- [patterns.md](./patterns.md) - Caching, sessions, rate limiting, A/B testing\n- [gotchas.md](./gotchas.md) - Eventual consistency, concurrent writes, value limits\n\n## See Also\n\n- [workers](../workers/) - Worker runtime for KV access\n- [d1](../d1/) - Use D1 for strong consistency needs\n- [durable-objects](../durable-objects/) - Strongly consistent alternative\n" }, { "path": "skills/.curated/cloudflare-deploy/references/kv/api.md", "content": "# KV API Reference\n\n## Read Operations\n\n```typescript\n// Single key (string)\nconst value = await env.MY_KV.get(\"user:123\");\n\n// JSON type (auto-parsed)\nconst config = await env.MY_KV.get(\"config\", \"json\");\n\n// ArrayBuffer for binary\nconst buffer = await env.MY_KV.get(\"image\", \"arrayBuffer\");\n\n// Stream for large values\nconst stream = await env.MY_KV.get(\"large-file\", \"stream\");\n\n// With cache TTL (min 60s)\nconst value = await env.MY_KV.get(\"key\", { type: \"text\", cacheTtl: 300 });\n\n// Bulk get (max 100 keys, counts as 1 operation)\nconst keys = [\"user:1\", \"user:2\", \"user:3\", \"missing:key\"];\nconst results = await env.MY_KV.get(keys);\n// Returns Map\n\nconsole.log(results.get(\"user:1\")); // \"John\" (if exists)\nconsole.log(results.get(\"missing:key\")); // null\n\n// Process results with null handling\nfor (const [key, value] of results) {\n if (value !== null) {\n // Handle found keys\n console.log(`${key}: ${value}`);\n }\n}\n\n// TypeScript with generics (type-safe JSON parsing)\ninterface UserProfile { name: string; email: string; }\nconst profile = await env.USERS.get(\"user:123\", \"json\");\n// profile is typed as UserProfile | null\nif (profile) {\n console.log(profile.name); // Type-safe access\n}\n\n// Bulk get with type\nconst configs = await env.MY_KV.get([\"config:app\", \"config:feature\"], \"json\");\n// Map\n```\n\n## Write Operations\n\n```typescript\n// Basic put\nawait env.MY_KV.put(\"key\", \"value\");\nawait env.MY_KV.put(\"config\", JSON.stringify({ theme: \"dark\" }));\n\n// With expiration (UNIX timestamp)\nawait env.MY_KV.put(\"session\", token, {\n expiration: Math.floor(Date.now() / 1000) + 3600\n});\n\n// With TTL (seconds from now, min 60)\nawait env.MY_KV.put(\"cache\", data, { expirationTtl: 300 });\n\n// With metadata (max 1024 bytes)\nawait env.MY_KV.put(\"user:profile\", userData, {\n metadata: { version: 2, lastUpdated: Date.now() }\n});\n\n// Combined\nawait env.MY_KV.put(\"temp\", value, {\n expirationTtl: 3600,\n metadata: { temporary: true }\n});\n```\n\n## Get with Metadata\n\n```typescript\n// Single key\nconst result = await env.MY_KV.getWithMetadata(\"user:profile\");\n// { value: string | null, metadata: any | null }\n\nif (result.value && result.metadata) {\n const { version, lastUpdated } = result.metadata;\n}\n\n// Multiple keys (bulk)\nconst keys = [\"key1\", \"key2\", \"key3\"];\nconst results = await env.MY_KV.getWithMetadata(keys);\n// Returns Map\n\nfor (const [key, result] of results) {\n if (result.value) {\n console.log(`${key}: ${result.value}`);\n console.log(`Metadata: ${JSON.stringify(result.metadata)}`);\n // cacheStatus field indicates cache hit/miss (when available)\n }\n}\n\n// With type\nconst result = await env.MY_KV.getWithMetadata(\"user:123\", \"json\");\n// result: { value: UserData | null, metadata: any | null, cacheStatus?: string }\n```\n\n## Delete Operations\n\n```typescript\nawait env.MY_KV.delete(\"key\"); // Always succeeds (even if key missing)\n```\n\n## List Operations\n\n```typescript\n// List all\nconst keys = await env.MY_KV.list();\n// { keys: [...], list_complete: boolean, cursor?: string }\n\n// With prefix\nconst userKeys = await env.MY_KV.list({ prefix: \"user:\" });\n\n// Pagination\nlet cursor: string | undefined;\nlet allKeys = [];\ndo {\n const result = await env.MY_KV.list({ cursor, limit: 1000 });\n allKeys.push(...result.keys);\n cursor = result.cursor;\n} while (!result.list_complete);\n```\n\n## Performance Considerations\n\n### Type Selection\n\n| Type | Use Case | Performance |\n|------|----------|-------------|\n| `stream` | Large values (>1MB) | Fastest - no buffering |\n| `arrayBuffer` | Binary data | Fast - single allocation |\n| `text` | String values | Medium |\n| `json` | Objects (parse overhead) | Slowest - parsing cost |\n\n### Parallel Reads\n\n```typescript\n// Efficient parallel reads with Promise.all()\nconst [user, settings, cache] = await Promise.all([\n env.USERS.get(\"user:123\", \"json\"),\n env.SETTINGS.get(\"config:app\", \"json\"),\n env.CACHE.get(\"data:latest\")\n]);\n```\n\n## Error Handling\n\n- **Missing keys:** Return `null` (not an error)\n- **Rate limit (429):** Retry with exponential backoff (see gotchas.md)\n- **Response too large (413):** Values >25MB fail with 413 error\n\nSee [gotchas.md](./gotchas.md) for detailed error patterns and solutions.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/kv/configuration.md", "content": "# KV Configuration\n\n## Create Namespace\n\n```bash\nwrangler kv namespace create MY_NAMESPACE\n# Output: { binding = \"MY_NAMESPACE\", id = \"abc123...\" }\n\nwrangler kv namespace create MY_NAMESPACE --preview # For local dev\n```\n\n## Workers Binding\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"kv_namespaces\": [\n {\n \"binding\": \"MY_KV\",\n \"id\": \"abc123xyz789\"\n },\n // Optional: Different namespace for preview/development\n {\n \"binding\": \"MY_KV\",\n \"preview_id\": \"preview-abc123\"\n }\n ]\n}\n```\n\n## TypeScript Types\n\n**env.d.ts:**\n```typescript\ninterface Env {\n MY_KV: KVNamespace;\n SESSIONS: KVNamespace;\n CACHE: KVNamespace;\n}\n```\n\n**worker.ts:**\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n // env.MY_KV is now typed as KVNamespace\n const value = await env.MY_KV.get(\"key\");\n return new Response(value || \"Not found\");\n }\n} satisfies ExportedHandler;\n```\n\n**Type-safe JSON operations:**\n```typescript\ninterface UserProfile {\n name: string;\n email: string;\n role: \"admin\" | \"user\";\n}\n\nconst profile = await env.USERS.get(\"user:123\", \"json\");\n// profile: UserProfile | null (type-safe!)\nif (profile) {\n console.log(profile.name); // TypeScript knows this is a string\n}\n```\n\n## CLI Operations\n\n```bash\n# Put\nwrangler kv key put --binding=MY_KV \"key\" \"value\"\nwrangler kv key put --binding=MY_KV \"key\" --path=./file.json --ttl=3600\n\n# Get\nwrangler kv key get --binding=MY_KV \"key\"\n\n# Delete\nwrangler kv key delete --binding=MY_KV \"key\"\n\n# List\nwrangler kv key list --binding=MY_KV --prefix=\"user:\"\n\n# Bulk operations (max 10,000 keys per file)\nwrangler kv bulk put data.json --binding=MY_KV\nwrangler kv bulk get keys.json --binding=MY_KV\nwrangler kv bulk delete keys.json --binding=MY_KV --force\n```\n\n## Local Development\n\n```bash\nwrangler dev # Local KV (isolated)\nwrangler dev --remote # Remote KV (production)\n\n# Or in wrangler.jsonc:\n# \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"...\", \"remote\": true }]\n```\n\n## REST API\n\n### Single Operations\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({\n apiEmail: process.env.CLOUDFLARE_EMAIL,\n apiKey: process.env.CLOUDFLARE_API_KEY\n});\n\n// Single key operations\nawait client.kv.namespaces.values.update(namespaceId, 'key', {\n account_id: accountId,\n value: 'value',\n expiration_ttl: 3600\n});\n```\n\n### Bulk Operations\n\n```typescript\n// Bulk update (up to 10,000 keys, max 100MB total)\nawait client.kv.namespaces.bulkUpdate(namespaceId, {\n account_id: accountId,\n body: [\n { key: \"key1\", value: \"value1\", expiration_ttl: 3600 },\n { key: \"key2\", value: \"value2\", metadata: { version: 1 } },\n { key: \"key3\", value: \"value3\" }\n ]\n});\n\n// Bulk get (up to 100 keys)\nconst results = await client.kv.namespaces.bulkGet(namespaceId, {\n account_id: accountId,\n keys: [\"key1\", \"key2\", \"key3\"]\n});\n\n// Bulk delete (up to 10,000 keys)\nawait client.kv.namespaces.bulkDelete(namespaceId, {\n account_id: accountId,\n keys: [\"key1\", \"key2\", \"key3\"]\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/kv/gotchas.md", "content": "# KV Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"Stale Read After Write\"\n\n**Cause:** Eventual consistency means writes may not be immediately visible in other regions \n**Solution:** Don't read immediately after write; return confirmation without reading or use the local value you just wrote. Writes visible immediately in same location, ≤60s globally\n\n```typescript\n// ❌ BAD: Read immediately after write\nawait env.KV.put(\"key\", \"value\");\nconst value = await env.KV.get(\"key\"); // May be null in other regions!\n\n// ✅ GOOD: Use the value you just wrote\nconst newValue = \"value\";\nawait env.KV.put(\"key\", newValue);\nreturn new Response(newValue); // Don't re-read\n```\n\n### \"429 Rate Limit on Concurrent Writes\"\n\n**Cause:** Multiple concurrent writes to same key exceeding 1 write/second limit \n**Solution:** Use sequential writes, unique keys for concurrent operations, or implement retry with exponential backoff\n\n```typescript\nasync function putWithRetry(\n kv: KVNamespace,\n key: string,\n value: string,\n maxAttempts = 5\n): Promise {\n let delay = 1000;\n for (let i = 0; i < maxAttempts; i++) {\n try {\n await kv.put(key, value);\n return;\n } catch (err) {\n if (err instanceof Error && err.message.includes(\"429\")) {\n if (i === maxAttempts - 1) throw err;\n await new Promise(r => setTimeout(r, delay));\n delay *= 2; // Exponential backoff\n } else {\n throw err;\n }\n }\n }\n}\n```\n\n### \"Inefficient Multiple Gets\"\n\n**Cause:** Making multiple individual get() calls instead of bulk operation \n**Solution:** Use bulk get with array of keys: `env.USERS.get([\"user:1\", \"user:2\", \"user:3\"])` to reduce to 1 operation\n\n### \"Null Reference Error\"\n\n**Cause:** Attempting to use value without checking for null when key doesn't exist \n**Solution:** Always handle null returns - KV returns `null` for missing keys, not undefined\n\n```typescript\n// ❌ BAD: Assumes value exists\nconst config = await env.KV.get(\"config\", \"json\");\nreturn config.theme; // TypeError if null!\n\n// ✅ GOOD: Null checks\nconst config = await env.KV.get(\"config\", \"json\");\nreturn config?.theme ?? \"default\";\n\n// ✅ GOOD: Early return\nconst config = await env.KV.get(\"config\", \"json\");\nif (!config) return new Response(\"Not found\", { status: 404 });\nreturn new Response(config.theme);\n```\n\n### \"Negative Lookup Caching\"\n\n**Cause:** Keys that don't exist are cached as \"not found\" for up to 60s \n**Solution:** Creating a key after checking won't be visible until cache expires\n\n```typescript\n// Check → create pattern has race condition\nconst exists = await env.KV.get(\"key\"); // null, cached as \"not found\"\nif (!exists) {\n await env.KV.put(\"key\", \"value\");\n // Next get() may still return null for ~60s due to negative cache\n}\n\n// Alternative: Always assume key may not exist, use defaults\nconst value = await env.KV.get(\"key\") ?? \"default-value\";\n```\n\n## Performance Tips\n\n| Scenario | Recommendation | Why |\n|----------|----------------|-----|\n| Large values (>1MB) | Use `stream` type | Avoids buffering entire value in memory |\n| Many small keys | Coalesce into one JSON object | Reduces operations, improves cache hit rate |\n| High write volume | Spread across different keys | Avoid 1 write/second per-key limit |\n| Cold reads | Increase `cacheTtl` parameter | Reduces latency for frequently-read data |\n| Bulk operations | Use array form of get() | Single operation, better performance |\n\n## Cost Examples\n\n**Free tier:**\n- 100K reads/day = 3M/month ✅\n- 1K writes/day = 30K/month ✅\n- 1GB storage ✅\n\n**Example paid workload:**\n- 10M reads/month = $5.00\n- 100K writes/month = $0.50\n- 1GB storage = $0.50\n- **Total: ~$6/month**\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Key size | 512 bytes | Maximum key length |\n| Value size | 25 MiB | Maximum value; 413 error if exceeded |\n| Metadata size | 1024 bytes | Maximum metadata per key |\n| cacheTtl minimum | 60s | Minimum cache TTL |\n| Write rate per key | 1 write/second | All plans; 429 error if exceeded |\n| Propagation time | ≤60s | Global propagation time |\n| Bulk get max | 100 keys | Maximum keys per bulk operation |\n| Operations per Worker | 1,000 | Per request (bulk counts as 1) |\n| Reads pricing | $0.50 per 10M | Per million reads |\n| Writes pricing | $5.00 per 1M | Per million writes |\n| Deletes pricing | $5.00 per 1M | Per million deletes |\n| Storage pricing | $0.50 per GB-month | Per GB per month |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/kv/patterns.md", "content": "# KV Patterns & Best Practices\n\n## Multi-Tier Caching\n\n```typescript\n// Memory → KV → Origin (3-tier cache)\nconst memoryCache = new Map();\n\nasync function getCached(env: Env, key: string): Promise {\n const now = Date.now();\n \n // L1: Memory cache (fastest)\n const cached = memoryCache.get(key);\n if (cached && cached.expires > now) {\n return cached.data;\n }\n \n // L2: KV cache (fast)\n const kvValue = await env.CACHE.get(key, \"json\");\n if (kvValue) {\n memoryCache.set(key, { data: kvValue, expires: now + 60000 }); // 1min in memory\n return kvValue;\n }\n \n // L3: Origin (slow)\n const origin = await fetch(`https://api.example.com/${key}`).then(r => r.json());\n \n // Backfill caches\n await env.CACHE.put(key, JSON.stringify(origin), { expirationTtl: 300 }); // 5min in KV\n memoryCache.set(key, { data: origin, expires: now + 60000 });\n \n return origin;\n}\n```\n\n## API Response Caching\n\n```typescript\nasync function getCachedData(env: Env, key: string, fetcher: () => Promise): Promise {\n const cached = await env.MY_KV.get(key, \"json\");\n if (cached) return cached;\n \n const data = await fetcher();\n await env.MY_KV.put(key, JSON.stringify(data), { expirationTtl: 300 });\n return data;\n}\n\nconst apiData = await getCachedData(\n env,\n \"cache:users\",\n () => fetch(\"https://api.example.com/users\").then(r => r.json())\n);\n```\n\n## Session Management\n\n```typescript\ninterface Session { userId: string; expiresAt: number; }\n\nasync function createSession(env: Env, userId: string): Promise {\n const sessionId = crypto.randomUUID();\n const expiresAt = Date.now() + (24 * 60 * 60 * 1000);\n \n await env.SESSIONS.put(\n `session:${sessionId}`,\n JSON.stringify({ userId, expiresAt }),\n { expirationTtl: 86400, metadata: { createdAt: Date.now() } }\n );\n \n return sessionId;\n}\n\nasync function getSession(env: Env, sessionId: string): Promise {\n const data = await env.SESSIONS.get(`session:${sessionId}`, \"json\");\n if (!data || data.expiresAt < Date.now()) return null;\n return data;\n}\n```\n\n## Coalesce Cold Keys\n\n```typescript\n// ❌ BAD: Many individual keys\nawait env.KV.put(\"user:123:name\", \"John\");\nawait env.KV.put(\"user:123:email\", \"john@example.com\");\n\n// ✅ GOOD: Single coalesced object\nawait env.USERS.put(\"user:123:profile\", JSON.stringify({\n name: \"John\",\n email: \"john@example.com\",\n role: \"admin\"\n}));\n\n// Benefits: Hot key cache, single read, reduced operations\n// Trade-off: Harder to update individual fields\n```\n\n## Prefix-Based Namespacing\n\n```typescript\n// Logical partitioning within single namespace\nconst PREFIXES = {\n users: \"user:\",\n sessions: \"session:\",\n cache: \"cache:\",\n features: \"feature:\"\n} as const;\n\n// Write with prefix\nasync function setUser(env: Env, id: string, data: any) {\n await env.KV.put(`${PREFIXES.users}${id}`, JSON.stringify(data));\n}\n\n// Read with prefix\nasync function getUser(env: Env, id: string) {\n return await env.KV.get(`${PREFIXES.users}${id}`, \"json\");\n}\n\n// List by prefix\nasync function listUserIds(env: Env): Promise {\n const result = await env.KV.list({ prefix: PREFIXES.users });\n return result.keys.map(k => k.name.replace(PREFIXES.users, \"\"));\n}\n\n// Example hierarchy\n\"user:123:profile\"\n\"user:123:settings\"\n\"cache:api:users\"\n\"session:abc-def\"\n\"feature:flags:beta\"\n```\n\n## Metadata Versioning\n\n```typescript\ninterface VersionedData {\n version: number;\n data: any;\n}\n\nasync function migrateIfNeeded(env: Env, key: string) {\n const result = await env.DATA.getWithMetadata(key, \"json\");\n \n if (!result.value) return null;\n \n const currentVersion = result.metadata?.version || 1;\n const targetVersion = 2;\n \n if (currentVersion < targetVersion) {\n // Migrate data format\n const migrated = migrate(result.value, currentVersion, targetVersion);\n \n // Store with new version\n await env.DATA.put(key, JSON.stringify(migrated), {\n metadata: { version: targetVersion, migratedAt: Date.now() }\n });\n \n return migrated;\n }\n \n return result.value;\n}\n\nfunction migrate(data: any, from: number, to: number): any {\n if (from === 1 && to === 2) {\n // V1 → V2: Rename field\n return { ...data, userName: data.name };\n }\n return data;\n}\n```\n\n## Error Boundary Pattern\n\n```typescript\n// Resilient get with fallback\nasync function resilientGet(\n env: Env,\n key: string,\n fallback: T\n): Promise {\n try {\n const value = await env.KV.get(key, \"json\");\n return value ?? fallback;\n } catch (err) {\n console.error(`KV error for ${key}:`, err);\n return fallback;\n }\n}\n\n// Usage\nconst config = await resilientGet(env, \"config:app\", {\n theme: \"light\",\n maxItems: 10\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/miniflare/README.md", "content": "# Miniflare\n\nLocal simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.\n\n## Features\n\n- Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues\n- Fully-local: test without internet, instant reload\n- TypeScript-native: detailed logging, source maps\n- Advanced testing: dispatch events without HTTP, simulate Worker connections\n\n## When to Use\n\n**Decision tree for testing Workers:**\n\n```\nNeed to test Workers?\n│\n├─ Unit tests for business logic only?\n│ └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)\n│ Fast, no HTTP, direct binding access\n│\n├─ Integration tests with full runtime?\n│ ├─ Single Worker?\n│ │ └─ Miniflare API → [Quick Start](#quick-start)\n│ │ Full control, programmatic access\n│ │\n│ ├─ Multiple Workers + service bindings?\n│ │ └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)\n│ │ Shared storage, inter-worker calls\n│ │\n│ └─ Vitest test runner integration?\n│ └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)\n│ Full Workers env in Vitest\n│\n└─ Local dev server?\n └─ wrangler dev (not Miniflare)\n Hot reload, automatic config\n```\n\n**Use Miniflare for:**\n- Integration tests with full Worker runtime\n- Testing bindings/storage locally\n- Multiple Workers with service bindings\n- Programmatic event dispatch (fetch, queue, scheduled)\n\n**Use getPlatformProxy for:**\n- Fast unit tests of business logic\n- Testing without HTTP overhead\n- Vitest/Jest environments\n\n**Use Wrangler for:**\n- Local development workflow\n- Production deployments\n\n## Setup\n\n```bash\nnpm i -D miniflare\n```\n\nRequires ES modules in `package.json`:\n```json\n{\"type\": \"module\"}\n```\n\n## Quick Start\n\n```js\nimport { Miniflare } from \"miniflare\";\n\nconst mf = new Miniflare({\n modules: true,\n script: `\n export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello Miniflare!\");\n }\n }\n `,\n});\n\nconst res = await mf.dispatchFetch(\"http://localhost:8787/\");\nconsole.log(await res.text()); // Hello Miniflare!\nawait mf.dispose();\n```\n\n## Reading Order\n\n**New to Miniflare?** Start here:\n1. [Quick Start](#quick-start) - Running in 2 minutes\n2. [When to Use](#when-to-use) - Choose your testing approach\n3. [patterns.md](./patterns.md) - Testing patterns (getPlatformProxy, Vitest, node:test)\n4. [configuration.md](./configuration.md) - Configure bindings, storage, multiple workers\n\n**Troubleshooting:**\n- [gotchas.md](./gotchas.md) - Common errors and debugging\n\n**API reference:**\n- [api.md](./api.md) - Complete method reference\n\n## See Also\n- [wrangler](../wrangler/) - CLI tool that embeds Miniflare for `wrangler dev`\n- [workerd](../workerd/) - Runtime that powers Miniflare\n- [workers](../workers/) - Workers runtime API documentation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/miniflare/api.md", "content": "# Programmatic API\n\n## Miniflare Class\n\n```typescript\nclass Miniflare {\n constructor(options: MiniflareOptions);\n \n // Lifecycle\n ready: Promise; // Resolves when server ready, returns URL\n dispose(): Promise; // Cleanup resources\n setOptions(options: MiniflareOptions): Promise; // Reload config\n \n // Event dispatching\n dispatchFetch(url: string | URL | Request, init?: RequestInit): Promise;\n getWorker(name?: string): Promise;\n \n // Bindings access\n getBindings>(name?: string): Promise;\n getCf(name?: string): Promise;\n getKVNamespace(name: string): Promise;\n getR2Bucket(name: string): Promise;\n getDurableObjectNamespace(name: string): Promise;\n getDurableObjectStorage(id: DurableObjectId): Promise;\n getD1Database(name: string): Promise;\n getCaches(): Promise;\n getQueueProducer(name: string): Promise;\n \n // Debugging\n getInspectorURL(): Promise; // Chrome DevTools inspector URL\n}\n```\n\n## Event Dispatching\n\n**Fetch (no HTTP server):**\n```js\nconst res = await mf.dispatchFetch(\"http://localhost:8787/path\", {\n method: \"POST\",\n headers: { \"Authorization\": \"Bearer token\" },\n body: JSON.stringify({ data: \"value\" }),\n});\n```\n\n**Custom Host routing:**\n```js\nconst res = await mf.dispatchFetch(\"http://localhost:8787/\", {\n headers: { \"Host\": \"api.example.com\" },\n});\n```\n\n**Scheduled:**\n```js\nconst worker = await mf.getWorker();\nconst result = await worker.scheduled({ cron: \"30 * * * *\" });\n// result: { outcome: \"ok\", noRetry: false }\n```\n\n**Queue:**\n```js\nconst worker = await mf.getWorker();\nconst result = await worker.queue(\"queue-name\", [\n { id: \"msg1\", timestamp: new Date(), body: \"data\", attempts: 1 },\n]);\n// result: { outcome: \"ok\", retryAll: false, ackAll: false, ... }\n```\n\n## Bindings Access\n\n**Environment variables:**\n```js\n// Basic usage\nconst bindings = await mf.getBindings();\nconsole.log(bindings.SECRET_KEY);\n\n// With type safety (recommended):\ninterface Env {\n SECRET_KEY: string;\n API_URL: string;\n KV: KVNamespace;\n}\nconst env = await mf.getBindings();\nenv.SECRET_KEY; // string (typed!)\nenv.KV.get(\"key\"); // KVNamespace methods available\n```\n\n**Request.cf object:**\n```js\nconst cf = await mf.getCf();\nconsole.log(cf?.colo); // \"DFW\"\nconsole.log(cf?.country); // \"US\"\n```\n\n**KV:**\n```js\nconst ns = await mf.getKVNamespace(\"TEST_NAMESPACE\");\nawait ns.put(\"key\", \"value\");\nconst value = await ns.get(\"key\");\n```\n\n**R2:**\n```js\nconst bucket = await mf.getR2Bucket(\"BUCKET\");\nawait bucket.put(\"file.txt\", \"content\");\nconst object = await bucket.get(\"file.txt\");\n```\n\n**Durable Objects:**\n```js\nconst ns = await mf.getDurableObjectNamespace(\"COUNTER\");\nconst id = ns.idFromName(\"test\");\nconst stub = ns.get(id);\nconst res = await stub.fetch(\"http://localhost/\");\n\n// Access storage directly:\nconst storage = await mf.getDurableObjectStorage(id);\nawait storage.put(\"key\", \"value\");\n```\n\n**D1:**\n```js\nconst db = await mf.getD1Database(\"DB\");\nawait db.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`);\nawait db.prepare(\"INSERT INTO users (name) VALUES (?)\").bind(\"Alice\").run();\n```\n\n**Cache:**\n```js\nconst caches = await mf.getCaches();\nconst defaultCache = caches.default;\nawait defaultCache.put(\"http://example.com\", new Response(\"cached\"));\n```\n\n**Queue producer:**\n```js\nconst producer = await mf.getQueueProducer(\"QUEUE\");\nawait producer.send({ body: \"message data\" });\n```\n\n## Lifecycle\n\n**Reload:**\n```js\nawait mf.setOptions({\n scriptPath: \"worker.js\",\n bindings: { VERSION: \"2.0\" },\n});\n```\n\n**Watch (manual):**\n```js\nimport { watch } from \"fs\";\n\nconst config = { scriptPath: \"worker.js\" };\nconst mf = new Miniflare(config);\n\nwatch(\"worker.js\", async () => {\n console.log(\"Reloading...\");\n await mf.setOptions(config);\n});\n```\n\n**Cleanup:**\n```js\nawait mf.dispose();\n```\n\n## Debugging\n\n**Inspector URL for DevTools:**\n```js\nconst url = await mf.getInspectorURL();\nconsole.log(`DevTools: ${url}`);\n// Open in Chrome DevTools for breakpoints, profiling\n```\n\n**Wait for server ready:**\n```js\nconst mf = new Miniflare({ scriptPath: \"worker.js\" });\nconst url = await mf.ready; // Promise\nconsole.log(`Server running at ${url}`); // http://127.0.0.1:8787\n\n// Note: dispatchFetch() waits automatically, no need to await ready\nconst res = await mf.dispatchFetch(\"http://localhost/\"); // Works immediately\n```\n\nSee [configuration.md](./configuration.md) for all constructor options.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/miniflare/configuration.md", "content": "# Configuration\n\n## Script Loading\n\n```js\n// Inline\nnew Miniflare({ modules: true, script: `export default { ... }` });\n\n// File-based\nnew Miniflare({ scriptPath: \"worker.js\" });\n\n// Multi-module\nnew Miniflare({\n scriptPath: \"src/index.js\",\n modules: true,\n modulesRules: [\n { type: \"ESModule\", include: [\"**/*.js\"] },\n { type: \"Text\", include: [\"**/*.txt\"] },\n ],\n});\n```\n\n## Compatibility\n\n```js\nnew Miniflare({\n compatibilityDate: \"2026-01-01\", // Use recent date for latest features\n compatibilityFlags: [\n \"nodejs_compat\", // Node.js APIs (process, Buffer, etc)\n \"streams_enable_constructors\", // Stream constructors\n ],\n upstream: \"https://example.com\", // Fallback for unhandled requests\n});\n```\n\n**Critical:** Use `compatibilityDate: \"2026-01-01\"` or latest to match production runtime. Old dates limit available APIs.\n\n## HTTP Server & Request.cf\n\n```js\nnew Miniflare({\n port: 8787, // Default: 8787\n host: \"127.0.0.1\",\n https: true, // Self-signed cert\n liveReload: true, // Auto-reload HTML\n \n cf: true, // Fetch live Request.cf data (cached)\n // cf: \"./cf.json\", // Or load from file\n // cf: { colo: \"DFW\" }, // Or inline mock\n});\n```\n\n**Note:** For tests, use `dispatchFetch()` (no port conflicts).\n\n## Storage Bindings\n\n```js\nnew Miniflare({\n // KV\n kvNamespaces: [\"TEST_NAMESPACE\", \"CACHE\"],\n kvPersist: \"./kv-data\", // Optional: persist to disk\n \n // R2\n r2Buckets: [\"BUCKET\", \"IMAGES\"],\n r2Persist: \"./r2-data\",\n \n // Durable Objects\n modules: true,\n durableObjects: {\n COUNTER: \"Counter\", // className\n API_OBJECT: { className: \"ApiObject\", scriptName: \"api-worker\" },\n },\n durableObjectsPersist: \"./do-data\",\n \n // D1\n d1Databases: [\"DB\"],\n d1Persist: \"./d1-data\",\n \n // Cache\n cache: true, // Default\n cachePersist: \"./cache-data\",\n});\n```\n\n## Bindings\n\n```js\nnew Miniflare({\n // Environment variables\n bindings: {\n SECRET_KEY: \"my-secret-value\",\n API_URL: \"https://api.example.com\",\n DEBUG: true,\n },\n \n // Other bindings\n wasmBindings: { ADD_MODULE: \"./add.wasm\" },\n textBlobBindings: { TEXT: \"./data.txt\" },\n queueProducers: [\"QUEUE\"],\n});\n```\n\n## Multiple Workers\n\n```js\nnew Miniflare({\n workers: [\n {\n name: \"main\",\n kvNamespaces: { DATA: \"shared\" },\n serviceBindings: { API: \"api-worker\" },\n script: `export default { ... }`,\n },\n {\n name: \"api-worker\",\n kvNamespaces: { DATA: \"shared\" }, // Shared storage\n script: `export default { ... }`,\n },\n ],\n});\n```\n\n**With routing:**\n```js\nworkers: [\n { name: \"api\", scriptPath: \"./api.js\", routes: [\"api.example.com/*\"] },\n { name: \"web\", scriptPath: \"./web.js\", routes: [\"example.com/*\"] },\n],\n```\n\n## Logging & Performance\n\n```js\nimport { Log, LogLevel } from \"miniflare\";\n\nnew Miniflare({\n log: new Log(LogLevel.DEBUG), // DEBUG | INFO | WARN | ERROR | NONE\n scriptTimeout: 30000, // CPU limit (ms)\n workersConcurrencyLimit: 10, // Max concurrent workers\n});\n```\n\n## Workers Sites\n\n```js\nnew Miniflare({\n sitePath: \"./public\",\n siteInclude: [\"**/*.html\", \"**/*.css\"],\n siteExclude: [\"**/*.map\"],\n});\n```\n\n## From wrangler.toml\n\nMiniflare doesn't auto-read `wrangler.toml`:\n\n```toml\n# wrangler.toml\nname = \"my-worker\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2026-01-01\"\n[[kv_namespaces]]\nbinding = \"KV\"\n```\n\n```js\n// Miniflare equivalent\nnew Miniflare({\n scriptPath: \"src/index.ts\",\n compatibilityDate: \"2026-01-01\",\n kvNamespaces: [\"KV\"],\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/miniflare/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Miniflare Limitations\n\n**Not supported:**\n- Analytics Engine (use mocks)\n- Cloudflare Images/Stream\n- Browser Rendering API\n- Tail Workers\n- Workers for Platforms (partial support)\n\n**Behavior differences from production:**\n- Runs workerd locally, not Cloudflare edge\n- Storage is local (filesystem/memory), not distributed\n- `Request.cf` is cached/mocked, not real edge data\n- Performance differs from edge\n- Caching implementation may vary slightly\n\n## Common Errors\n\n### \"Cannot find module\"\n**Cause:** Module path wrong or `modulesRules` not configured \n**Solution:**\n```js\nnew Miniflare({\n modules: true,\n modulesRules: [{ type: \"ESModule\", include: [\"**/*.js\"] }],\n});\n```\n\n### \"Data not persisting\"\n**Cause:** Persist paths are files, not directories \n**Solution:**\n```js\nkvPersist: \"./data/kv\", // Directory, not file\n```\n\n### \"Cannot run TypeScript\"\n**Cause:** Miniflare doesn't transpile TypeScript \n**Solution:** Build first with esbuild/tsc, then run compiled JS\n\n### \"`request.cf` is undefined\"\n**Cause:** CF data not configured \n**Solution:**\n```js\nnew Miniflare({ cf: true }); // Or cf: \"./cf.json\"\n```\n\n### \"EADDRINUSE\" port conflict\n**Cause:** Multiple instances using same port \n**Solution:** Use `dispatchFetch()` (no HTTP server) or `port: 0` for auto-assign\n\n### \"Durable Object not found\"\n**Cause:** Class export doesn't match config name \n**Solution:**\n```js\nexport class Counter {} // Must match\nnew Miniflare({ durableObjects: { COUNTER: \"Counter\" } });\n```\n\n## Debugging\n\n**Enable verbose logging:**\n```js\nimport { Log, LogLevel } from \"miniflare\";\nnew Miniflare({ log: new Log(LogLevel.DEBUG) });\n```\n\n**Chrome DevTools:**\n```js\nconst url = await mf.getInspectorURL();\nconsole.log(`DevTools: ${url}`); // Open in Chrome\n```\n\n**Inspect bindings:**\n```js\nconst env = await mf.getBindings();\nconsole.log(Object.keys(env));\n```\n\n**Verify storage:**\n```js\nconst ns = await mf.getKVNamespace(\"TEST\");\nconst { keys } = await ns.list();\n```\n\n## Best Practices\n\n**✓ Do:**\n- Use `dispatchFetch()` for tests (no HTTP server)\n- In-memory storage for CI (omit persist options)\n- New instances per test for isolation\n- Type-safe bindings with interfaces\n- `await mf.dispose()` in cleanup\n\n**✗ Avoid:**\n- HTTP server in tests\n- Shared instances without cleanup\n- Old compatibility dates (use 2026+)\n\n## Migration Guides\n\n### From Miniflare 2.x to 3+\n\nBreaking changes in v3+:\n\n| v2 | v3+ |\n|----|-----|\n| `getBindings()` sync | `getBindings()` returns Promise |\n| `ready` is void | `ready` returns `Promise` |\n| service-worker-mock | Built on workerd |\n| Different options | Restructured constructor |\n\n**Example migration:**\n```js\n// v2\nconst bindings = mf.getBindings();\nmf.ready; // void\n\n// v3+\nconst bindings = await mf.getBindings();\nconst url = await mf.ready; // Promise\n```\n\n### From unstable_dev to Miniflare\n\n```js\n// Old (deprecated)\nimport { unstable_dev } from \"wrangler\";\nconst worker = await unstable_dev(\"src/index.ts\");\n\n// New\nimport { Miniflare } from \"miniflare\";\nconst mf = new Miniflare({ scriptPath: \"src/index.ts\" });\n```\n\n### From Wrangler Dev\n\nMiniflare doesn't auto-read `wrangler.toml`:\n\n```js\n// Translate manually:\nnew Miniflare({\n scriptPath: \"dist/worker.js\",\n compatibilityDate: \"2026-01-01\",\n kvNamespaces: [\"KV\"],\n bindings: { API_KEY: process.env.API_KEY },\n});\n```\n\n## Resource Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| CPU time | 30s default | Configurable via `scriptTimeout` |\n| Storage | Filesystem | Performance varies by disk |\n| Memory | System dependent | No artificial limits |\n| Request.cf | Cached/mocked | Not live edge data |\n\nSee [patterns.md](./patterns.md) for testing examples.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/miniflare/patterns.md", "content": "# Testing Patterns\n\n## Choosing a Testing Approach\n\n| Approach | Use Case | Speed | Setup | Runtime |\n|----------|----------|-------|-------|---------|\n| **getPlatformProxy** | Unit tests, logic testing | Fast | Low | Miniflare |\n| **Miniflare API** | Integration tests, full control | Medium | Medium | Miniflare |\n| **vitest-pool-workers** | Vitest runner integration | Medium | Medium | workerd |\n\n**Quick guide:**\n- Unit tests → getPlatformProxy\n- Integration tests → Miniflare API\n- Vitest workflows → vitest-pool-workers\n\n## getPlatformProxy\n\nLightweight unit testing - provides bindings without full Worker runtime.\n\n```js\n// vitest.config.js\nexport default { test: { environment: \"node\" } };\n```\n\n```js\nimport { env } from \"cloudflare:test\";\nimport { describe, it, expect } from \"vitest\";\n\ndescribe(\"Business logic\", () => {\n it(\"processes data with KV\", async () => {\n await env.KV.put(\"test\", \"value\");\n expect(await env.KV.get(\"test\")).toBe(\"value\");\n });\n});\n```\n\n**Pros:** Fast, simple \n**Cons:** No full runtime, can't test fetch handler\n\n## vitest-pool-workers\n\nFull Workers runtime in Vitest. Reads `wrangler.toml`.\n\n```bash\nnpm i -D @cloudflare/vitest-pool-workers\n```\n\n```js\n// vitest.config.js\nimport { defineWorkersConfig } from \"@cloudflare/vitest-pool-workers/config\";\n\nexport default defineWorkersConfig({\n test: {\n poolOptions: { workers: { wrangler: { configPath: \"./wrangler.toml\" } } },\n },\n});\n```\n\n```js\nimport { env, SELF } from \"cloudflare:test\";\nimport { it, expect } from \"vitest\";\n\nit(\"handles fetch\", async () => {\n const res = await SELF.fetch(\"http://example.com/\");\n expect(res.status).toBe(200);\n});\n```\n\n**Pros:** Full runtime, uses wrangler.toml \n**Cons:** Requires Wrangler config\n\n## Miniflare API (node:test)\n\n```js\nimport assert from \"node:assert\";\nimport test, { after, before } from \"node:test\";\nimport { Miniflare } from \"miniflare\";\n\nlet mf;\nbefore(() => {\n mf = new Miniflare({ scriptPath: \"src/index.js\", kvNamespaces: [\"TEST_KV\"] });\n});\n\ntest(\"fetch\", async () => {\n const res = await mf.dispatchFetch(\"http://localhost/\");\n assert.strictEqual(await res.text(), \"Hello\");\n});\n\nafter(() => mf.dispose());\n```\n\n## Testing Durable Objects & Events\n\n```js\n// Durable Objects\nconst ns = await mf.getDurableObjectNamespace(\"COUNTER\");\nconst stub = ns.get(ns.idFromName(\"test-counter\"));\nawait stub.fetch(\"http://localhost/increment\");\n\n// Direct storage\nconst storage = await mf.getDurableObjectStorage(ns.idFromName(\"test-counter\"));\nconst count = await storage.get(\"count\");\n\n// Queue\nconst worker = await mf.getWorker();\nawait worker.queue(\"my-queue\", [\n { id: \"msg1\", timestamp: new Date(), body: { userId: 123 }, attempts: 1 },\n]);\n\n// Scheduled\nawait worker.scheduled({ cron: \"0 0 * * *\" });\n```\n\n## Test Isolation & Mocking\n\n```js\n// Per-test isolation\nbeforeEach(() => { mf = new Miniflare({ kvNamespaces: [\"TEST\"] }); });\nafterEach(() => mf.dispose());\n\n// Mock external APIs\nnew Miniflare({\n workers: [\n { name: \"main\", serviceBindings: { API: \"mock-api\" }, script: `...` },\n { name: \"mock-api\", script: `export default { async fetch() { return Response.json({mock: true}); } }` },\n ],\n});\n```\n\n## Type Safety\n\n```ts\nimport type { KVNamespace } from \"@cloudflare/workers-types\";\n\ninterface Env {\n KV: KVNamespace;\n API_KEY: string;\n}\n\nconst env = await mf.getBindings();\nawait env.KV.put(\"key\", \"value\"); // Typed!\n\nexport default {\n async fetch(req: Request, env: Env) {\n return new Response(await env.KV.get(\"key\"));\n }\n} satisfies ExportedHandler;\n```\n\n## WebSocket Testing\n\n```js\nconst res = await mf.dispatchFetch(\"http://localhost/ws\", {\n headers: { Upgrade: \"websocket\" },\n});\nassert.strictEqual(res.status, 101);\n```\n\n## Migration from unstable_dev\n\n```js\n// Old (deprecated)\nimport { unstable_dev } from \"wrangler\";\nconst worker = await unstable_dev(\"src/index.ts\");\n\n// New\nimport { Miniflare } from \"miniflare\";\nconst mf = new Miniflare({ scriptPath: \"src/index.ts\" });\n```\n\n## CI/CD Tips\n\n```js\n// In-memory storage (faster)\nnew Miniflare({ kvNamespaces: [\"TEST\"] }); // No persist = in-memory\n\n// Use dispatchFetch (no port conflicts)\nawait mf.dispatchFetch(\"http://localhost/\");\n```\n\nSee [gotchas.md](./gotchas.md) for troubleshooting.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/network-interconnect/README.md", "content": "# Cloudflare Network Interconnect (CNI)\n\nPrivate, high-performance connectivity to Cloudflare's network. **Enterprise-only**.\n\n## Connection Types\n\n**Direct**: Physical fiber in shared datacenter. 10/100 Gbps. You order cross-connect.\n\n**Partner**: Virtual via Console Connect, Equinix, Megaport, etc. Managed via partner SDN.\n\n**Cloud**: AWS Direct Connect or GCP Cloud Interconnect. Magic WAN only.\n\n## Dataplane Versions\n\n**v1 (Classic)**: GRE tunnel support, VLAN/BFD/LACP, asymmetric MTU (1500↓/1476↑), peering support.\n\n**v2 (Beta)**: No GRE, 1500 MTU both ways, no VLAN/BFD/LACP yet, ECMP instead.\n\n## Use Cases\n\n- **Magic Transit DSR**: DDoS protection, egress via ISP (v1/v2)\n- **Magic Transit + Egress**: DDoS + egress via CF (v1/v2)\n- **Magic WAN + Zero Trust**: Private backbone (v1 needs GRE, v2 native)\n- **Peering**: Public routes at PoP (v1 only)\n- **App Security**: WAF/Cache/LB (v1/v2 over Magic Transit)\n\n## Prerequisites\n\n- Enterprise plan\n- IPv4 /24+ or IPv6 /48+ prefixes\n- BGP ASN for v1\n- See [locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-2026-01.pdf)\n\n## Specs\n\n- /31 point-to-point subnets\n- 10km max optical distance\n- 10G: 10GBASE-LR single-mode\n- 100G: 100GBASE-LR4 single-mode\n- **No SLA** (free service)\n- Backup Internet required\n\n## Throughput\n\n| Direction | 10G | 100G |\n|-----------|-----|------|\n| CF → Customer | 10 Gbps | 100 Gbps |\n| Customer → CF (peering) | 10 Gbps | 100 Gbps |\n| Customer → CF (Magic) | 1 Gbps/tunnel or CNI | 1 Gbps/tunnel or CNI |\n\n## Timeline\n\n2-4 weeks typical. Steps: request → config review → order connection → configure → test → enable health checks → activate → monitor.\n\n## In This Reference\n- [configuration.md](./configuration.md) - BGP, routing, setup\n- [api.md](./api.md) - API endpoints, SDKs\n- [patterns.md](./patterns.md) - HA, hybrid cloud, failover\n- [gotchas.md](./gotchas.md) - Troubleshooting, limits\n\n## Reading Order by Task\n\n| Task | Files to Load |\n|------|---------------|\n| Initial setup | README → configuration.md → api.md |\n| Create interconnect via API | api.md → gotchas.md |\n| Design HA architecture | patterns.md → README |\n| Troubleshoot connection | gotchas.md → configuration.md |\n| Cloud integration (AWS/GCP) | configuration.md → patterns.md |\n| Monitor + alerts | configuration.md |\n\n## Automation Boundary\n\n**API-Automatable:**\n- List/create/delete interconnects (Direct, Partner)\n- List available slots\n- Get interconnect status\n- Download LOA PDF\n- Create/update CNI objects (BGP config)\n- Query settings\n\n**Requires Account Team:**\n- Initial request approval\n- AWS Direct Connect setup (send LOA+VLAN to CF)\n- GCP Cloud Interconnect final activation\n- Partner interconnect acceptance (Equinix, Megaport)\n- VLAN assignment (v1)\n- Configuration document generation (v1)\n- Escalations + troubleshooting support\n\n**Cannot Be Automated:**\n- Physical cross-connect installation (Direct)\n- Partner portal operations (virtual circuit ordering)\n- AWS/GCP portal operations\n- Maintenance window coordination\n\n## See Also\n- [tunnel](../tunnel/) - Alternative for private network connectivity\n- [spectrum](../spectrum/) - Layer 4 proxy for TCP/UDP traffic\n" }, { "path": "skills/.curated/cloudflare-deploy/references/network-interconnect/api.md", "content": "# CNI API Reference\n\nSee [README.md](README.md) for overview.\n\n## Base\n\n```\nhttps://api.cloudflare.com/client/v4\nAuth: Authorization: Bearer \n```\n\n## SDK Namespaces\n\n**Primary (recommended):**\n```typescript\nclient.networkInterconnects.interconnects.*\nclient.networkInterconnects.cnis.*\nclient.networkInterconnects.slots.*\n```\n\n**Alternate (deprecated):**\n```typescript\nclient.magicTransit.cfInterconnects.*\n```\n\nUse `networkInterconnects` namespace for all new code.\n\n## Interconnects\n\n```http\nGET /accounts/{account_id}/cni/interconnects # Query: page, per_page\nPOST /accounts/{account_id}/cni/interconnects # Query: validate_only=true (optional)\nGET /accounts/{account_id}/cni/interconnects/{icon}\nGET /accounts/{account_id}/cni/interconnects/{icon}/status\nGET /accounts/{account_id}/cni/interconnects/{icon}/loa # Returns PDF\nDELETE /accounts/{account_id}/cni/interconnects/{icon}\n```\n\n**Create Body:** `account`, `slot_id`, `type`, `facility`, `speed`, `name`, `description` \n**Status Values:** `active` | `healthy` | `unhealthy` | `pending` | `down`\n\n**Response Example:**\n```json\n{\"result\": [{\"id\": \"icon_abc\", \"name\": \"prod\", \"type\": \"direct\", \"facility\": \"EWR1\", \"speed\": \"10G\", \"status\": \"active\"}]}\n```\n\n## CNI Objects (BGP config)\n\n```http\nGET /accounts/{account_id}/cni/cnis\nPOST /accounts/{account_id}/cni/cnis\nGET /accounts/{account_id}/cni/cnis/{cni}\nPUT /accounts/{account_id}/cni/cnis/{cni}\nDELETE /accounts/{account_id}/cni/cnis/{cni}\n```\n\nBody: `account`, `cust_ip`, `cf_ip`, `bgp_asn`, `bgp_password`, `vlan`\n\n## Slots\n\n```http\nGET /accounts/{account_id}/cni/slots\nGET /accounts/{account_id}/cni/slots/{slot}\n```\n\nQuery: `facility`, `occupied`, `speed`\n\n## Health Checks\n\nConfigure via Magic Transit/WAN tunnel endpoints (CNI v2).\n\n```typescript\nawait client.magicTransit.tunnels.update(accountId, tunnelId, {\n health_check: { enabled: true, target: '192.0.2.1', rate: 'high', type: 'request' },\n});\n```\n\nRates: `high` | `medium` | `low`. Types: `request` | `reply`. See [Magic Transit docs](https://developers.cloudflare.com/magic-transit/how-to/configure-tunnel-endpoints/#add-tunnels).\n\n## Settings\n\n```http\nGET /accounts/{account_id}/cni/settings\nPUT /accounts/{account_id}/cni/settings\n```\n\nBody: `default_asn`\n\n## TypeScript SDK\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: process.env.CF_TOKEN });\n\n// List\nawait client.networkInterconnects.interconnects.list({ account_id: id });\n\n// Create with validation\nawait client.networkInterconnects.interconnects.create({\n account_id: id,\n account: id,\n slot_id: 'slot_abc',\n type: 'direct',\n facility: 'EWR1',\n speed: '10G',\n name: 'prod-interconnect',\n}, {\n query: { validate_only: true }, // Dry-run validation\n});\n\n// Create without validation\nawait client.networkInterconnects.interconnects.create({\n account_id: id,\n account: id,\n slot_id: 'slot_abc',\n type: 'direct',\n facility: 'EWR1',\n speed: '10G',\n name: 'prod-interconnect',\n});\n\n// Status\nawait client.networkInterconnects.interconnects.get(accountId, iconId);\n\n// LOA (use fetch)\nconst res = await fetch(`https://api.cloudflare.com/client/v4/accounts/${id}/cni/interconnects/${iconId}/loa`, {\n headers: { Authorization: `Bearer ${token}` },\n});\nawait fs.writeFile('loa.pdf', Buffer.from(await res.arrayBuffer()));\n\n// CNI object\nawait client.networkInterconnects.cnis.create({\n account_id: id,\n account: id,\n cust_ip: '192.0.2.1/31',\n cf_ip: '192.0.2.0/31',\n bgp_asn: 65000,\n vlan: 100,\n});\n\n// Slots (filter by facility and speed)\nawait client.networkInterconnects.slots.list({\n account_id: id,\n occupied: false,\n facility: 'EWR1',\n speed: '10G',\n});\n```\n\n## Python SDK\n\n```python\nfrom cloudflare import Cloudflare\n\nclient = Cloudflare(api_token=os.environ[\"CF_TOKEN\"])\n\n# List, create, status (same pattern as TypeScript)\nclient.network_interconnects.interconnects.list(account_id=id)\nclient.network_interconnects.interconnects.create(account_id=id, account=id, slot_id=\"slot_abc\", type=\"direct\", facility=\"EWR1\", speed=\"10G\")\nclient.network_interconnects.interconnects.get(account_id=id, icon=icon_id)\n\n# CNI objects and slots\nclient.network_interconnects.cnis.create(account_id=id, cust_ip=\"192.0.2.1/31\", cf_ip=\"192.0.2.0/31\", bgp_asn=65000)\nclient.network_interconnects.slots.list(account_id=id, occupied=False)\n```\n\n## cURL\n\n```bash\n# List interconnects\ncurl \"https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects\" \\\n -H \"Authorization: Bearer ${CF_TOKEN}\"\n\n# Create interconnect\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects?validate_only=true\" \\\n -H \"Authorization: Bearer ${CF_TOKEN}\" -H \"Content-Type: application/json\" \\\n -d '{\"account\": \"id\", \"slot_id\": \"slot_abc\", \"type\": \"direct\", \"facility\": \"EWR1\", \"speed\": \"10G\"}'\n\n# LOA PDF\ncurl \"https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects/${ICON_ID}/loa\" \\\n -H \"Authorization: Bearer ${CF_TOKEN}\" --output loa.pdf\n```\n\n## Not Available via API\n\n**Missing Capabilities:**\n- BGP session state query (use Dashboard or BGP logs)\n- Bandwidth utilization metrics (use external monitoring)\n- Traffic statistics per interconnect\n- Historical uptime/downtime data\n- Light level readings (contact account team)\n- Maintenance window scheduling (notifications only)\n\n## Resources\n\n- [API Docs](https://developers.cloudflare.com/api/resources/network_interconnects/)\n- [TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)\n- [Python SDK](https://github.com/cloudflare/cloudflare-python)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/network-interconnect/configuration.md", "content": "# CNI Configuration\n\nSee [README.md](README.md) for overview.\n\n## Workflow (2-4 weeks)\n\n1. **Submit request** (Week 1): Contact account team, provide type/location/use case\n2. **Review config** (Week 1-2, v1 only): Approve IP/VLAN/spec doc\n3. **Order connection** (Week 2-3):\n - **Direct**: Get LOA, order cross-connect from facility\n - **Partner**: Order virtual circuit in partner portal\n - **Cloud**: Order Direct Connect/Cloud Interconnect, send LOA+VLAN to CF\n4. **Configure** (Week 3): Both sides configure per doc\n5. **Test** (Week 3-4): Ping, verify BGP, check routes\n6. **Health checks** (Week 4): Configure [Magic Transit](https://developers.cloudflare.com/magic-transit/how-to/configure-tunnel-endpoints/#add-tunnels) or [Magic WAN](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-tunnel-endpoints/#add-tunnels) health checks\n7. **Activate** (Week 4): Route traffic, verify flow\n8. **Monitor**: Enable [maintenance notifications](https://developers.cloudflare.com/network-interconnect/monitoring-and-alerts/#enable-cloudflare-status-maintenance-notification)\n\n## BGP Configuration\n\n**v1 Requirements:**\n- BGP ASN (provide during setup)\n- /31 subnet for peering\n- Optional: BGP password\n\n**v2:** Simplified, less BGP config needed.\n\n**BGP over CNI (Dec 2024):** Magic WAN/Transit can now peer BGP directly over CNI v2 (no GRE tunnel required).\n\n**Example v1 BGP:**\n```\nRouter ID: 192.0.2.1\nPeer IP: 192.0.2.0\nRemote ASN: 13335\nLocal ASN: 65000\nPassword: [optional]\nVLAN: 100\n```\n\n## Cloud Interconnect Setup\n\n### AWS Direct Connect (Beta)\n\n**Requirements:** Magic WAN, AWS Dedicated Direct Connect 1/10 Gbps.\n\n**Process:**\n1. Contact CF account team\n2. Choose location\n3. Order in AWS portal\n4. AWS provides LOA + VLAN ID\n5. Send to CF account team\n6. Wait ~4 weeks\n\n**Post-setup:** Add [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes) to Magic WAN. Enable [bidirectional health checks](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-tunnel-endpoints/#legacy-bidirectional-health-checks).\n\n### GCP Cloud Interconnect (Beta)\n\n**Setup via Dashboard:**\n1. Interconnects → Create → Cloud Interconnect → Google\n2. Provide name, MTU (match GCP VLAN attachment), speed (50M-50G granular options available for partner interconnects)\n3. Enter VLAN attachment pairing key\n4. Confirm order\n\n**Routing to GCP:** Add [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes). BGP routes from GCP Cloud Router **ignored**.\n\n**Routing to CF:** Configure [custom learned routes](https://cloud.google.com/network-connectivity/docs/router/how-to/configure-custom-learned-routes) in Cloud Router. Request prefixes from CF account team.\n\n## Monitoring\n\n**Dashboard Status:**\n\n| Status | Meaning |\n|--------|---------|\n| **Healthy** | Link operational, traffic flowing, health checks passing |\n| **Active** | Link up, sufficient light, Ethernet negotiated |\n| **Unhealthy** | Link down, no/low light (<-20 dBm), can't negotiate |\n| **Pending** | Cross-connect incomplete, device unresponsive, RX/TX swapped |\n| **Down** | Physical link down, no connectivity |\n\n**Alerts:**\n\n**CNI Connection Maintenance** (Magic Networking only):\n```\nDashboard → Notifications → Add\nProduct: Cloudflare Network Interconnect\nType: Connection Maintenance Alert\n```\nWarnings up to 2 weeks advance. 6hr delay for new additions.\n\n**Cloudflare Status Maintenance** (entire PoP):\n```\nDashboard → Notifications → Add\nProduct: Cloudflare Status\nFilter PoPs: gru,fra,lhr\n```\n\n**Find PoP code:**\n```\nDashboard → Magic Transit/WAN → Configuration → Interconnects\nSelect CNI → Note Data Center (e.g., \"gru-b\")\nUse first 3 letters: \"gru\"\n```\n\n## Best Practices\n\n**Critical config-specific practices:**\n- /31 subnets required for BGP\n- BGP passwords recommended\n- BFD for fast failover (v1 only)\n- Test ping connectivity before BGP\n- Enable maintenance notifications immediately after activation\n- Monitor status programmatically via API\n\nFor design patterns, HA architecture, and security best practices, see [patterns.md](./patterns.md).\n" }, { "path": "skills/.curated/cloudflare-deploy/references/network-interconnect/gotchas.md", "content": "# CNI Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"Status: Pending\"\n\n**Cause:** Cross-connect not installed, RX/TX fibers reversed, wrong fiber type, or low light levels\n**Solution:**\n1. Verify cross-connect installed\n2. Check fiber at patch panel\n3. Swap RX/TX fibers\n4. Check light with optical power meter (target > -20 dBm)\n5. Contact account team\n\n### \"Status: Unhealthy\"\n\n**Cause:** Physical issue, low light (<-20 dBm), optic mismatch, or dirty connectors\n**Solution:**\n1. Check physical connections\n2. Clean fiber connectors\n3. Verify optic types (10GBASE-LR/100GBASE-LR4)\n4. Test with known-good optics\n5. Check patch panel\n6. Contact account team\n\n### \"BGP Session Down\"\n\n**Cause:** Wrong IP addressing, wrong ASN, password mismatch, or firewall blocking TCP/179\n**Solution:**\n1. Verify IPs match CNI object\n2. Confirm ASN correct\n3. Check BGP password\n4. Verify no firewall on TCP/179\n5. Check BGP logs\n6. Review BGP timers\n\n### \"Low Throughput\"\n\n**Cause:** MTU mismatch, fragmentation, single GRE tunnel (v1), or routing inefficiency\n**Solution:**\n1. Check MTU (1500↓/1476↑ for v1, 1500 both for v2)\n2. Test various packet sizes\n3. Add more GRE tunnels (v1)\n4. Consider upgrading to v2\n5. Review routing tables\n6. Use LACP for bundling (v1)\n\n## API Errors\n\n### 400 Bad Request: \"slot_id already occupied\"\n\n**Cause:** Another interconnect already uses this slot \n**Solution:** Use `occupied=false` filter when listing slots:\n```typescript\nawait client.networkInterconnects.slots.list({\n account_id: id,\n occupied: false,\n facility: 'EWR1',\n});\n```\n\n### 400 Bad Request: \"invalid facility code\"\n\n**Cause:** Typo or unsupported facility \n**Solution:** Check [locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-2026-01.pdf) for valid codes\n\n### 403 Forbidden: \"Enterprise plan required\"\n\n**Cause:** Account not enterprise-level \n**Solution:** Contact account team to upgrade\n\n### 422 Unprocessable: \"validate_only request failed\"\n\n**Cause:** Dry-run validation found issues (wrong slot, invalid config) \n**Solution:** Review error message details, fix config before real creation\n\n### Rate Limiting\n\n**Limit:** 1200 requests/5min per token \n**Solution:** Implement exponential backoff, cache slot listings\n\n## Cloud-Specific Issues\n\n### AWS Direct Connect: \"VLAN not matching\"\n\n**Cause:** VLAN ID from AWS LOA doesn't match CNI config \n**Solution:**\n1. Get VLAN from AWS Console after ordering\n2. Send exact VLAN to CF account team\n3. Verify match in CNI object config\n\n### AWS: \"Connection stuck in Pending\"\n\n**Cause:** LOA not provided to CF or AWS connection not accepted \n**Solution:**\n1. Verify AWS connection status is \"Available\"\n2. Confirm LOA sent to CF account team\n3. Wait for CF team acceptance (can take days)\n\n### GCP: \"BGP routes not propagating\"\n\n**Cause:** BGP routes from GCP Cloud Router **ignored by design** \n**Solution:** Use [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes) in Magic WAN instead\n\n### GCP: \"Cannot query VLAN attachment status via API\"\n\n**Cause:** GCP Cloud Interconnect Dashboard-only (no API yet) \n**Solution:** Check status in CF Dashboard or GCP Console\n\n## Partner Interconnect Issues\n\n### Equinix: \"Virtual circuit not appearing\"\n\n**Cause:** CF hasn't accepted Equinix connection request \n**Solution:**\n1. Verify VC created in Equinix Fabric Portal\n2. Contact CF account team to accept\n3. Allow 2-3 business days\n\n### Console Connect/Megaport: \"API creation fails\"\n\n**Cause:** Partner interconnects require partner portal + CF approval \n**Solution:** Cannot fully automate. Order in partner portal, notify CF account team.\n\n## Anti-Patterns\n\n| Anti-Pattern | Why Bad | Solution |\n|--------------|---------|----------|\n| Single interconnect for production | No SLA, single point of failure | Use ≥2 with device diversity |\n| No backup Internet | CNI fails = total outage | Always maintain alternate path |\n| Polling status every second | Rate limits, wastes API calls | Poll every 30-60s max |\n| Using v1 for Magic WAN v2 workloads | GRE overhead, complexity | Use v2 for simplified routing |\n| Assuming BGP session = traffic flowing | BGP up ≠ routes installed | Verify routing tables + test traffic |\n| Not enabling maintenance alerts | Surprise downtime during maintenance | Enable notifications immediately |\n| Hardcoding VLAN in automation | VLAN assigned by CF (v1) | Get VLAN from CNI object response |\n| Using Direct without colocation | Can't access cross-connect | Use Partner or Cloud interconnect |\n\n## What's Not Queryable via API\n\n**Cannot retrieve:**\n- BGP session state (use Dashboard or BGP logs)\n- Light levels (contact account team)\n- Historical metrics (uptime, traffic)\n- Bandwidth utilization per interconnect\n- Maintenance window schedules (notifications only)\n- Fiber path details\n- Cross-connect installation status\n\n**Workarounds:**\n- External monitoring for BGP state\n- Log aggregation for historical data\n- Notifications for maintenance windows\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Max optical distance | 10km | Physical limit |\n| MTU (v1) | 1500↓ / 1476↑ | Asymmetric |\n| MTU (v2) | 1500 both | Symmetric |\n| GRE tunnel throughput | 1 Gbps | Per tunnel (v1) |\n| Recovery time | Days | No formal SLA |\n| Light level minimum | -20 dBm | Target threshold |\n| API rate limit | 1200 req/5min | Per token |\n| Health check delay | 6 hours | New maintenance alert subscriptions |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/network-interconnect/patterns.md", "content": "# CNI Patterns\n\nSee [README.md](README.md) for overview.\n\n## High Availability\n\n**Critical:** Design for resilience from day one.\n\n**Requirements:**\n- Device-level diversity (separate hardware)\n- Backup Internet connectivity (no SLA on CNI)\n- Network-resilient locations preferred\n- Regular failover testing\n\n**Architecture:**\n```\nYour Network A ──10G CNI v2──> CF CCR Device 1\n │\nYour Network B ──10G CNI v2──> CF CCR Device 2\n │\n CF Global Network (AS13335)\n```\n\n**Capacity Planning:**\n- Plan across all links\n- Account for failover scenarios\n- Your responsibility\n\n## Pattern: Magic Transit + CNI v2\n\n**Use Case:** DDoS protection, private connectivity, no GRE overhead.\n\n```typescript\n// 1. Create interconnect\nconst ic = await client.networkInterconnects.interconnects.create({\n account_id: id,\n type: 'direct',\n facility: 'EWR1',\n speed: '10G',\n name: 'magic-transit-primary',\n});\n\n// 2. Poll until active\nconst status = await pollUntilActive(id, ic.id);\n\n// 3. Configure Magic Transit tunnel via Dashboard/API\n```\n\n**Benefits:** 1500 MTU both ways, simplified routing.\n\n## Pattern: Multi-Cloud Hybrid\n\n**Use Case:** AWS/GCP workloads with Cloudflare.\n\n**AWS Direct Connect:**\n```typescript\n// 1. Order Direct Connect in AWS Console\n// 2. Get LOA + VLAN from AWS\n// 3. Send to CF account team (no API)\n// 4. Configure static routes in Magic WAN\n\nawait configureStaticRoutes(id, {\n prefix: '10.0.0.0/8',\n nexthop: 'aws-direct-connect',\n});\n```\n\n**GCP Cloud Interconnect:**\n```\n1. Get VLAN attachment pairing key from GCP Console\n2. Create via Dashboard: Interconnects → Create → Cloud Interconnect → Google\n - Enter pairing key, name, MTU, speed\n3. Configure static routes in Magic WAN (BGP routes from GCP ignored)\n4. Configure custom learned routes in GCP Cloud Router\n```\n\n**Note:** Dashboard-only. No API/SDK support yet.\n\n## Pattern: Multi-Location HA\n\n**Use Case:** 99.99%+ uptime.\n\n```typescript\n// Primary (NY)\nconst primary = await client.networkInterconnects.interconnects.create({\n account_id: id,\n type: 'direct',\n facility: 'EWR1',\n speed: '10G',\n name: 'primary-ewr1',\n});\n\n// Secondary (NY, different hardware)\nconst secondary = await client.networkInterconnects.interconnects.create({\n account_id: id,\n type: 'direct',\n facility: 'EWR2',\n speed: '10G',\n name: 'secondary-ewr2',\n});\n\n// Tertiary (LA, different geography)\nconst tertiary = await client.networkInterconnects.interconnects.create({\n account_id: id,\n type: 'partner',\n facility: 'LAX1',\n speed: '10G',\n name: 'tertiary-lax1',\n});\n\n// BGP local preferences:\n// Primary: 200\n// Secondary: 150\n// Tertiary: 100\n// Internet: Last resort\n```\n\n## Pattern: Partner Interconnect (Equinix)\n\n**Use Case:** Quick deployment, no colocation.\n\n**Setup:**\n1. Order virtual circuit in Equinix Fabric Portal\n2. Select Cloudflare as destination\n3. Choose facility\n4. Send details to CF account team\n5. CF accepts in portal\n6. Configure BGP\n\n**No API automation** – partner portals managed separately.\n\n## Failover & Security\n\n**Failover Best Practices:**\n- Use BGP local preferences for priority\n- Configure BFD for fast detection (v1)\n- Test regularly with traffic shift\n- Document runbooks\n\n**Security:**\n- BGP password authentication\n- BGP route filtering\n- Monitor unexpected routes\n- Magic Firewall for DDoS/threats\n- Minimum API token permissions\n- Rotate credentials periodically\n\n## Decision Matrix\n\n| Requirement | Recommended |\n|-------------|-------------|\n| Collocated with CF | Direct |\n| Not collocated | Partner |\n| AWS/GCP workloads | Cloud |\n| 1500 MTU both ways | v2 |\n| VLAN tagging | v1 |\n| Public peering | v1 |\n| Simplest config | v2 |\n| BFD fast failover | v1 |\n| LACP bundling | v1 |\n\n## Resources\n\n- [Magic Transit Docs](https://developers.cloudflare.com/magic-transit/)\n- [Magic WAN Docs](https://developers.cloudflare.com/magic-wan/)\n- [Argo Smart Routing](https://developers.cloudflare.com/argo/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/observability/README.md", "content": "# Cloudflare Observability Skill Reference\n\n**Purpose**: Comprehensive guidance for implementing observability in Cloudflare Workers, covering traces, logs, metrics, and analytics.\n\n**Scope**: Cloudflare Observability features ONLY - Workers Logs, Traces, Analytics Engine, Logpush, Metrics & Analytics, and OpenTelemetry exports.\n\n---\n\n## Decision Tree: Which File to Load?\n\nUse this to route to the correct file without loading all content:\n\n```\n├─ \"How do I enable/configure X?\" → configuration.md\n├─ \"What's the API/method/binding for X?\" → api.md\n├─ \"How do I implement X pattern?\" → patterns.md\n│ ├─ Usage tracking/billing → patterns.md\n│ ├─ Error tracking → patterns.md\n│ ├─ Performance monitoring → patterns.md\n│ ├─ Multi-tenant tracking → patterns.md\n│ ├─ Tail Worker filtering → patterns.md\n│ └─ OpenTelemetry export → patterns.md\n└─ \"Why isn't X working?\" / \"Limits?\" → gotchas.md\n```\n\n## Reading Order\n\nLoad files in this order based on task:\n\n| Task Type | Load Order | Reason |\n|-----------|------------|--------|\n| **Initial setup** | configuration.md → gotchas.md | Setup first, avoid pitfalls |\n| **Implement feature** | patterns.md → api.md → gotchas.md | Pattern → API details → edge cases |\n| **Debug issue** | gotchas.md → configuration.md | Common issues first |\n| **Query data** | api.md → patterns.md | API syntax → query examples |\n\n## Product Overview\n\n### Workers Logs\n- **What:** Console output from Workers (console.log/warn/error)\n- **Access:** Dashboard (Real-time Logs), Logpush, Tail Workers\n- **Cost:** Free (included with all Workers)\n- **Retention:** Real-time only (no historical storage in dashboard)\n\n### Workers Traces\n- **What:** Execution traces with timing, CPU usage, outcome\n- **Access:** Dashboard (Workers Analytics → Traces), Logpush\n- **Cost:** $0.10/1M spans (GA pricing starts March 1, 2026), 10M free/month\n- **Retention:** 14 days included\n\n### Analytics Engine\n- **What:** High-cardinality event storage and SQL queries\n- **Access:** SQL API, Dashboard (Analytics → Analytics Engine)\n- **Cost:** $0.25/1M writes beyond 10M free/month\n- **Retention:** 90 days (configurable up to 1 year)\n\n### Tail Workers\n- **What:** Workers that receive logs/traces from other Workers\n- **Use Cases:** Log filtering, transformation, external export\n- **Cost:** Standard Workers pricing\n\n### Logpush\n- **What:** Stream logs to external storage (S3, R2, Datadog, etc.)\n- **Access:** Dashboard, API\n- **Cost:** Requires Business/Enterprise plan\n\n## Pricing Summary (2026)\n\n| Feature | Free Tier | Cost Beyond Free Tier | Plan Requirement |\n|---------|-----------|----------------------|------------------|\n| Workers Logs | Unlimited | Free | Any |\n| Workers Traces | 10M spans/month | $0.10/1M spans | Paid Workers (GA: March 1, 2026) |\n| Analytics Engine | 10M writes/month | $0.25/1M writes | Paid Workers |\n| Logpush | N/A | Included in plan | Business/Enterprise |\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, configuration (Logs, Traces, Analytics Engine, Tail Workers, Logpush)\n- **[api.md](api.md)** - API endpoints, methods, interfaces (GraphQL, SQL, bindings, types)\n- **[patterns.md](patterns.md)** - Common patterns, use cases, examples (billing, monitoring, error tracking, exports)\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations (common errors, performance gotchas, pricing)\n\n## See Also\n\n- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)\n- [Analytics Engine Docs](https://developers.cloudflare.com/analytics/analytics-engine/)\n- [Workers Traces Docs](https://developers.cloudflare.com/workers/observability/traces/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/observability/api.md", "content": "## API Reference\n\n### GraphQL Analytics API\n\n**Endpoint**: `https://api.cloudflare.com/client/v4/graphql`\n\n**Query Workers Metrics**:\n```graphql\nquery {\n viewer {\n accounts(filter: { accountTag: $accountId }) {\n workersInvocationsAdaptive(\n limit: 100\n filter: {\n datetime_geq: \"2025-01-01T00:00:00Z\"\n datetime_leq: \"2025-01-31T23:59:59Z\"\n scriptName: \"my-worker\"\n }\n ) {\n sum {\n requests\n errors\n subrequests\n }\n quantiles {\n cpuTimeP50\n cpuTimeP99\n wallTimeP50\n wallTimeP99\n }\n }\n }\n }\n}\n```\n\n### Analytics Engine SQL API\n\n**Endpoint**: `https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql`\n\n**Authentication**: `Authorization: Bearer ` (Account Analytics Read permission)\n\n**Common Queries**:\n\n```sql\n-- List all datasets\nSHOW TABLES;\n\n-- Time-series aggregation (5-minute buckets)\nSELECT\n intDiv(toUInt32(timestamp), 300) * 300 AS time_bucket,\n blob1 AS endpoint,\n SUM(_sample_interval) AS total_requests,\n AVG(double1) AS avg_response_time_ms\nFROM api_metrics\nWHERE timestamp >= NOW() - INTERVAL '24' HOUR\nGROUP BY time_bucket, endpoint\nORDER BY time_bucket DESC;\n\n-- Top customers by usage\nSELECT\n index1 AS customer_id,\n SUM(_sample_interval * double1) AS total_api_calls,\n AVG(double2) AS avg_response_time_ms\nFROM api_usage\nWHERE timestamp >= NOW() - INTERVAL '7' DAY\nGROUP BY customer_id\nORDER BY total_api_calls DESC\nLIMIT 100;\n\n-- Error rate analysis\nSELECT\n blob1 AS error_type,\n COUNT(*) AS occurrences,\n MAX(timestamp) AS last_seen\nFROM error_tracking\nWHERE timestamp >= NOW() - INTERVAL '1' HOUR\nGROUP BY error_type\nORDER BY occurrences DESC;\n```\n\n### Console Logging API\n\n**Methods**:\n```typescript\n// Standard methods (all appear in Workers Logs)\nconsole.log('info message');\nconsole.info('info message');\nconsole.warn('warning message');\nconsole.error('error message');\nconsole.debug('debug message');\n\n// Structured logging (recommended)\nconsole.log({\n level: 'info',\n user_id: '123',\n action: 'checkout',\n amount: 99.99,\n currency: 'USD'\n});\n```\n\n**Log Levels**: All console methods produce logs; use structured fields for filtering:\n```typescript\nconsole.log({ \n level: 'error', \n message: 'Payment failed', \n error_code: 'CARD_DECLINED' \n});\n```\n\n### Analytics Engine Binding Types\n\n```typescript\ninterface AnalyticsEngineDataset {\n writeDataPoint(event: AnalyticsEngineDataPoint): void;\n}\n\ninterface AnalyticsEngineDataPoint {\n // Indexed strings (use for filtering/grouping)\n indexes?: string[];\n \n // Non-indexed strings (metadata, IDs, URLs)\n blobs?: string[];\n \n // Numeric values (counts, durations, amounts)\n doubles?: number[];\n}\n```\n\n**Field Limits**:\n- Max 20 indexes\n- Max 20 blobs\n- Max 20 doubles\n- Max 25 `writeDataPoint` calls per request\n\n### Tail Consumer Event Type\n\n```typescript\ninterface TraceItem {\n event: TraceEvent;\n logs: TraceLog[];\n exceptions: TraceException[];\n scriptName?: string;\n}\n\ninterface TraceEvent {\n outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' | 'unknown';\n cpuTime: number; // microseconds\n wallTime: number; // microseconds\n}\n\ninterface TraceLog {\n timestamp: number;\n level: 'log' | 'info' | 'debug' | 'warn' | 'error';\n message: any; // string or structured object\n}\n\ninterface TraceException {\n name: string;\n message: string;\n timestamp: number;\n}\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/observability/configuration.md", "content": "## Configuration Patterns\n\n### Enable Workers Logs\n\n```jsonc\n{\n \"observability\": {\n \"enabled\": true,\n \"head_sampling_rate\": 1 // 100% sampling (default)\n }\n}\n```\n\n**Best Practice**: Use structured JSON logging for better indexing\n\n```typescript\n// Good - structured logging\nconsole.log({ \n user_id: 123, \n action: \"login\", \n status: \"success\",\n duration_ms: 45\n});\n\n// Avoid - unstructured string\nconsole.log(\"user_id: 123 logged in successfully in 45ms\");\n```\n\n### Enable Workers Traces\n\n```jsonc\n{\n \"observability\": {\n \"traces\": {\n \"enabled\": true,\n \"head_sampling_rate\": 0.05 // 5% sampling\n }\n }\n}\n```\n\n**Note**: Default sampling is 100%. For high-traffic Workers, use lower sampling (0.01-0.1).\n\n### Configure Analytics Engine\n\n**Bind to Worker**:\n```toml\n# wrangler.toml\nanalytics_engine_datasets = [\n { binding = \"ANALYTICS\", dataset = \"api_metrics\" }\n]\n```\n\n**Write Data Points**:\n```typescript\nexport interface Env {\n ANALYTICS: AnalyticsEngineDataset;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // Track metrics\n env.ANALYTICS.writeDataPoint({\n blobs: ['customer_123', 'POST', '/api/v1/users'],\n doubles: [1, 245.5], // request_count, response_time_ms\n indexes: ['customer_123'] // for efficient filtering\n });\n \n return new Response('OK');\n }\n}\n```\n\n### Configure Tail Workers\n\nTail Workers receive logs/traces from other Workers for filtering, transformation, or export.\n\n**Setup**:\n```toml\n# wrangler.toml\nname = \"log-processor\"\nmain = \"src/tail.ts\"\n\n[[tail_consumers]]\nservice = \"my-worker\" # Worker to tail\n```\n\n**Tail Worker Example**:\n```typescript\nexport default {\n async tail(events: TraceItem[], env: Env, ctx: ExecutionContext) {\n // Filter errors only\n const errors = events.filter(event => \n event.outcome === 'exception' || event.outcome === 'exceededCpu'\n );\n \n if (errors.length > 0) {\n // Send to external monitoring\n ctx.waitUntil(\n fetch('https://monitoring.example.com/errors', {\n method: 'POST',\n body: JSON.stringify(errors)\n })\n );\n }\n }\n}\n```\n\n### Configure Logpush\n\nSend logs to external storage (S3, R2, GCS, Azure, Datadog, etc.). Requires Business/Enterprise plan.\n\n**Via Dashboard**:\n1. Navigate to Analytics → Logs → Logpush\n2. Select destination type\n3. Provide credentials and bucket/endpoint\n4. Choose dataset (e.g., Workers Trace Events)\n5. Configure filters and fields\n\n**Via API**:\n```bash\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/logpush/jobs\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"workers-logs-to-s3\",\n \"destination_conf\": \"s3://my-bucket/logs?region=us-east-1\",\n \"dataset\": \"workers_trace_events\",\n \"enabled\": true,\n \"frequency\": \"high\",\n \"filter\": \"{\\\"where\\\":{\\\"and\\\":[{\\\"key\\\":\\\"ScriptName\\\",\\\"operator\\\":\\\"eq\\\",\\\"value\\\":\\\"my-worker\\\"}]}}\"\n }'\n```\n\n### Environment-Specific Configuration\n\n**Development** (verbose logs, full sampling):\n```jsonc\n// wrangler.dev.jsonc\n{\n \"observability\": {\n \"enabled\": true,\n \"head_sampling_rate\": 1.0,\n \"traces\": {\n \"enabled\": true\n }\n }\n}\n```\n\n**Production** (reduced sampling, structured logs):\n```jsonc\n// wrangler.prod.jsonc\n{\n \"observability\": {\n \"enabled\": true,\n \"head_sampling_rate\": 0.1, // 10% sampling\n \"traces\": {\n \"enabled\": true\n }\n }\n}\n```\n\nDeploy with env-specific config:\n```bash\nwrangler deploy --config wrangler.prod.jsonc --env production\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/observability/gotchas.md", "content": "## Common Errors\n\n### \"Logs not appearing\"\n\n**Cause:** Observability disabled, Worker not redeployed, no traffic, low sampling rate, or log size exceeds 256 KB\n**Solution:** \n```bash\n# Verify config\ncat wrangler.jsonc | jq '.observability'\n\n# Check deployment\nwrangler deployments list \n\n# Test with curl\ncurl https://your-worker.workers.dev\n```\nEnsure `observability.enabled = true`, redeploy Worker, check `head_sampling_rate`, verify traffic\n\n### \"Traces not being captured\"\n\n**Cause:** Traces not enabled, incorrect sampling rate, Worker not redeployed, or destination unavailable\n**Solution:**\n```jsonc\n// Temporarily set to 100% sampling for debugging\n{\n \"observability\": {\n \"enabled\": true,\n \"head_sampling_rate\": 1.0,\n \"traces\": {\n \"enabled\": true\n }\n }\n}\n```\nEnsure `observability.traces.enabled = true`, set `head_sampling_rate` to 1.0 for testing, redeploy, check destination status\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Max log size | 256 KB | Logs exceeding this are truncated |\n| Default sampling rate | 1.0 (100%) | Reduce for high-traffic Workers |\n| Max destinations | Varies by plan | Check dashboard |\n| Trace context propagation | 100 spans max | Deep call chains may lose spans |\n| Analytics Engine write rate | 25 writes/request | Excess writes dropped silently |\n\n## Performance Gotchas\n\n### Spectre Mitigation Timing\n\n**Problem:** `Date.now()` and `performance.now()` have reduced precision (coarsened to 100μs)\n**Cause:** Spectre vulnerability mitigation in V8\n**Solution:** Accept reduced precision or use Workers Traces for accurate timing\n```typescript\n// Date.now() is coarsened - trace spans are accurate\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n // For user-facing timing, Date.now() is fine\n const start = Date.now();\n const response = await processRequest(request);\n const duration = Date.now() - start;\n \n // For detailed performance analysis, use Workers Traces instead\n return response;\n }\n}\n```\n\n### Analytics Engine _sample_interval Aggregation\n\n**Problem:** Queries return incorrect totals when not multiplying by `_sample_interval`\n**Cause:** Analytics Engine stores sampled data points, each representing multiple events\n**Solution:** Always multiply counts/sums by `_sample_interval` in aggregations\n```sql\n-- WRONG: Undercounts actual events\nSELECT blob1 AS customer_id, COUNT(*) AS total_calls\nFROM api_usage GROUP BY customer_id;\n\n-- CORRECT: Accounts for sampling\nSELECT blob1 AS customer_id, SUM(_sample_interval) AS total_calls\nFROM api_usage GROUP BY customer_id;\n```\n\n### Trace Context Propagation Limits\n\n**Problem:** Deep call chains lose trace context after 100 spans\n**Cause:** Cloudflare limits trace depth to prevent performance impact\n**Solution:** Design for flatter architectures or use custom correlation IDs for deep chains\n```typescript\n// For deep call chains, add custom correlation ID\nconst correlationId = crypto.randomUUID();\nconsole.log({ correlationId, event: 'request_start' });\n\n// Pass correlationId through headers to downstream services\nawait fetch('https://api.example.com', {\n headers: { 'X-Correlation-ID': correlationId }\n});\n```\n\n## Pricing (2026)\n\n### Workers Traces\n- **GA Pricing (starts March 1, 2026):**\n - $0.10 per 1M trace spans captured\n - Retention: 14 days included\n- **Free tier:** 10M trace spans/month\n- **Note:** Beta usage (before March 1, 2026) is free\n\n### Workers Logs\n- **Included:** Free for all Workers\n- **Logpush:** Requires Business/Enterprise plan\n\n### Analytics Engine\n- **Included:** 10M writes/month on Paid Workers plan\n- **Additional:** $0.25 per 1M writes beyond included quota\n" }, { "path": "skills/.curated/cloudflare-deploy/references/observability/patterns.md", "content": "# Observability Patterns\n\n## Usage-Based Billing\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [customerId, request.url, request.method],\n doubles: [1], // request_count\n indexes: [customerId]\n});\n```\n\n```sql\nSELECT blob1 AS customer_id, SUM(_sample_interval * double1) AS total_calls\nFROM api_usage WHERE timestamp >= DATE_TRUNC('month', NOW())\nGROUP BY customer_id\n```\n\n## Performance Monitoring\n\n```typescript\nconst start = Date.now();\nconst response = await fetch(url);\nenv.ANALYTICS.writeDataPoint({\n blobs: [url, response.status.toString()],\n doubles: [Date.now() - start, response.status]\n});\n```\n\n```sql\nSELECT blob1 AS url, AVG(double1) AS avg_ms, percentile(double1, 0.95) AS p95_ms\nFROM fetch_metrics WHERE timestamp >= NOW() - INTERVAL '1' HOUR\nGROUP BY url\n```\n\n## Error Tracking\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n blobs: [error.name, request.url, request.method],\n doubles: [1],\n indexes: [error.name]\n});\n```\n\n## Multi-Tenant Tracking\n\n```typescript\nenv.ANALYTICS.writeDataPoint({\n indexes: [tenantId], // efficient filtering\n blobs: [tenantId, url.pathname, method, status],\n doubles: [1, duration, bytesSize]\n});\n```\n\n## Tail Worker Log Filtering\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n const critical = events.filter(e => \n e.exceptions.length > 0 || e.event.wallTime > 1000000\n );\n if (critical.length === 0) return;\n \n ctx.waitUntil(\n fetch('https://logging.example.com/ingest', {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${env.API_KEY}` },\n body: JSON.stringify(critical.map(e => ({\n outcome: e.event.outcome,\n cpu_ms: e.event.cpuTime / 1000,\n errors: e.exceptions\n })))\n })\n );\n }\n};\n```\n\n## OpenTelemetry Export\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n const otelSpans = events.map(e => ({\n traceId: generateId(32),\n spanId: generateId(16),\n name: e.scriptName || 'worker.request',\n attributes: [\n { key: 'worker.outcome', value: { stringValue: e.event.outcome } },\n { key: 'worker.cpu_time_us', value: { intValue: String(e.event.cpuTime) } }\n ]\n }));\n \n ctx.waitUntil(\n fetch('https://api.honeycomb.io/v1/traces', {\n method: 'POST',\n headers: { 'X-Honeycomb-Team': env.HONEYCOMB_KEY },\n body: JSON.stringify({ resourceSpans: [{ scopeSpans: [{ spans: otelSpans }] }] })\n })\n );\n }\n};\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages/README.md", "content": "# Cloudflare Pages\n\nJAMstack platform for full-stack apps on Cloudflare's global network.\n\n## Key Features\n\n- **Git-based deploys**: Auto-deploy from GitHub/GitLab\n- **Preview deployments**: Unique URL per branch/PR\n- **Pages Functions**: File-based serverless routing (Workers runtime)\n- **Static + dynamic**: Smart asset caching + edge compute\n- **Smart Placement**: Automatic function optimization based on traffic patterns\n- **Framework optimized**: SvelteKit, Astro, Nuxt, Qwik, Solid Start\n\n## Deployment Methods\n\n### 1. Git Integration (Production)\nDashboard → Workers & Pages → Create → Connect to Git → Configure build\n\n### 2. Direct Upload\n```bash\nnpx wrangler pages deploy ./dist --project-name=my-project\nnpx wrangler pages deploy ./dist --project-name=my-project --branch=staging\n```\n\n### 3. C3 CLI\n```bash\nnpm create cloudflare@latest my-app\n# Select framework → auto-setup + deploy\n```\n\n## vs Workers\n\n- **Pages**: Static sites, JAMstack, frameworks, git workflow, file-based routing\n- **Workers**: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers\n- **Combine**: Pages Functions use Workers runtime, can bind to Workers\n\n## Quick Start\n\n```bash\n# Create\nnpm create cloudflare@latest\n\n# Local dev\nnpx wrangler pages dev ./dist\n\n# Deploy\nnpx wrangler pages deploy ./dist --project-name=my-project\n\n# Types\nnpx wrangler types --path='./functions/types.d.ts'\n\n# Secrets\necho \"value\" | npx wrangler pages secret put KEY --project-name=my-project\n\n# Logs\nnpx wrangler pages deployment tail --project-name=my-project\n```\n\n## Resources\n\n- [Pages Docs](https://developers.cloudflare.com/pages/)\n- [Functions API](https://developers.cloudflare.com/pages/functions/api-reference/)\n- [Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)\n- [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)\n\n## Reading Order\n\n**New to Pages?** Start here:\n1. README.md (you are here) - Overview & quick start\n2. [configuration.md](./configuration.md) - Project setup, wrangler.jsonc, bindings\n3. [api.md](./api.md) - Functions API, routing, context\n4. [patterns.md](./patterns.md) - Common implementations\n5. [gotchas.md](./gotchas.md) - Troubleshooting & pitfalls\n\n**Quick reference?** Jump to relevant file above.\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc, build, env vars, Smart Placement\n- [api.md](./api.md) - Functions API, bindings, context, advanced mode\n- [patterns.md](./patterns.md) - Full-stack patterns, framework integration\n- [gotchas.md](./gotchas.md) - Build issues, limits, debugging, framework warnings\n\n## See Also\n\n- [pages-functions](../pages-functions/) - File-based routing, middleware\n- [d1](../d1/) - SQL database for Pages Functions\n- [kv](../kv/) - Key-value storage for caching/state\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages/api.md", "content": "# Functions API\n\n## File-Based Routing\n\n```\n/functions/index.ts → example.com/\n/functions/api/users.ts → example.com/api/users\n/functions/api/users/[id].ts → example.com/api/users/:id\n/functions/api/users/[[path]].ts → example.com/api/users/* (catchall)\n/functions/_middleware.ts → Runs before all routes\n```\n\n**Rules**: `[param]` = single segment, `[[param]]` = multi-segment catchall, more specific wins.\n\n## Request Handlers\n\n```typescript\nimport type { PagesFunction } from '@cloudflare/workers-types';\n\ninterface Env {\n DB: D1Database;\n KV: KVNamespace;\n}\n\n// All methods\nexport const onRequest: PagesFunction = async (context) => {\n return new Response('All methods');\n};\n\n// Method-specific\nexport const onRequestGet: PagesFunction = async (context) => {\n const { request, env, params, data } = context;\n \n const user = await env.DB.prepare(\n 'SELECT * FROM users WHERE id = ?'\n ).bind(params.id).first();\n \n return Response.json(user);\n};\n\nexport const onRequestPost: PagesFunction = async (context) => {\n const body = await context.request.json();\n return Response.json({ success: true });\n};\n\n// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions\n```\n\n## Context Object\n\n```typescript\ninterface EventContext {\n request: Request; // HTTP request\n env: Env; // Bindings (KV, D1, R2, etc.)\n params: Params; // Route parameters\n data: Data; // Middleware-shared data\n waitUntil: (promise: Promise) => void; // Background tasks\n next: () => Promise; // Next handler\n passThroughOnException: () => void; // Error fallback (not in advanced mode)\n}\n```\n\n## Dynamic Routes\n\n```typescript\n// Single segment: functions/users/[id].ts\nexport const onRequestGet: PagesFunction = async ({ params }) => {\n // /users/123 → params.id = \"123\"\n return Response.json({ userId: params.id });\n};\n\n// Multi-segment: functions/files/[[path]].ts\nexport const onRequestGet: PagesFunction = async ({ params }) => {\n // /files/docs/api/v1.md → params.path = [\"docs\", \"api\", \"v1.md\"]\n const filePath = (params.path as string[]).join('/');\n return new Response(filePath);\n};\n```\n\n## Middleware\n\n```typescript\n// functions/_middleware.ts\n// Single\nexport const onRequest: PagesFunction = async (context) => {\n const response = await context.next();\n response.headers.set('X-Custom-Header', 'value');\n return response;\n};\n\n// Chained (runs in order)\nconst errorHandler: PagesFunction = async (context) => {\n try {\n return await context.next();\n } catch (err) {\n return new Response(err.message, { status: 500 });\n }\n};\n\nconst auth: PagesFunction = async (context) => {\n const token = context.request.headers.get('Authorization');\n if (!token) return new Response('Unauthorized', { status: 401 });\n context.data.userId = await verifyToken(token);\n return context.next();\n};\n\nexport const onRequest = [errorHandler, auth];\n```\n\n**Scope**: `functions/_middleware.ts` → all; `functions/api/_middleware.ts` → `/api/*` only\n\n## Bindings Usage\n\n```typescript\nexport const onRequestGet: PagesFunction = async ({ env }) => {\n // KV\n const cached = await env.KV.get('key', 'json');\n await env.KV.put('key', JSON.stringify({data: 'value'}), {expirationTtl: 3600});\n \n // D1\n const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n \n // R2, Queue, AI - see respective reference docs\n \n return Response.json({success: true});\n};\n```\n\n## Advanced Mode\n\nFull Workers API, bypasses file-based routing:\n\n```javascript\n// functions/_worker.js\nexport default {\n async fetch(request, env, ctx) {\n const url = new URL(request.url);\n \n // Custom routing\n if (url.pathname.startsWith('/api/')) {\n return new Response('API response');\n }\n \n // REQUIRED: Serve static assets\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**When to use**: WebSockets, complex routing, scheduled handlers, email handlers.\n\n## Smart Placement\n\nAutomatically optimizes function execution location based on traffic patterns.\n\n**Configuration** (in wrangler.jsonc):\n```jsonc\n{\n \"placement\": {\n \"mode\": \"smart\" // Enables optimization (default: off)\n }\n}\n```\n\n**How it works**: Analyzes traffic patterns over time and places functions closer to users or data sources (e.g., D1 databases). Requires no code changes.\n\n**Trade-offs**: Initial requests may see slightly higher latency during learning period (hours-days). Performance improves as system optimizes.\n\n**When to use**: Global apps with centralized databases or geographically concentrated traffic sources.\n\n## getRequestContext (Framework SSR)\n\nAccess bindings in framework code:\n\n```typescript\n// SvelteKit\nimport type { RequestEvent } from '@sveltejs/kit';\nexport async function load({ platform }: RequestEvent) {\n const data = await platform.env.DB.prepare('SELECT * FROM users').all();\n return { users: data.results };\n}\n\n// Astro\nconst { DB } = Astro.locals.runtime.env;\nconst data = await DB.prepare('SELECT * FROM users').all();\n\n// Solid Start (server function)\nimport { getRequestEvent } from 'solid-js/web';\nconst event = getRequestEvent();\nconst data = await event.locals.runtime.env.DB.prepare('SELECT * FROM users').all();\n```\n\n**✅ Supported adapters** (2026):\n- **SvelteKit**: `@sveltejs/adapter-cloudflare`\n- **Astro**: Built-in Cloudflare adapter\n- **Nuxt**: Set `nitro.preset: 'cloudflare-pages'` in `nuxt.config.ts`\n- **Qwik**: Built-in Cloudflare adapter\n- **Solid Start**: `@solidjs/start-cloudflare-pages`\n\n**❌ Deprecated/Unsupported**:\n- **Next.js**: Official adapter (`@cloudflare/next-on-pages`) deprecated. Use Vercel or self-host on Workers.\n- **Remix**: Official adapter (`@remix-run/cloudflare-pages`) deprecated. Migrate to supported frameworks.\n\nSee [gotchas.md](./gotchas.md#framework-specific) for migration guidance.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages/configuration.md", "content": "# Configuration\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"name\": \"my-pages-project\",\n \"pages_build_output_dir\": \"./dist\",\n \"compatibility_date\": \"2026-01-01\", // Use current date for new projects\n \"compatibility_flags\": [\"nodejs_compat\"],\n \"placement\": {\n \"mode\": \"smart\" // Optional: Enable Smart Placement\n },\n \"kv_namespaces\": [{\"binding\": \"KV\", \"id\": \"abcd1234...\"}],\n \"d1_databases\": [{\"binding\": \"DB\", \"database_id\": \"xxxx-xxxx\", \"database_name\": \"production-db\"}],\n \"r2_buckets\": [{\"binding\": \"BUCKET\", \"bucket_name\": \"my-bucket\"}],\n \"durable_objects\": {\"bindings\": [{\"name\": \"COUNTER\", \"class_name\": \"Counter\", \"script_name\": \"counter-worker\"}]},\n \"services\": [{\"binding\": \"API\", \"service\": \"api-worker\"}],\n \"queues\": {\"producers\": [{\"binding\": \"QUEUE\", \"queue\": \"my-queue\"}]},\n \"vectorize\": [{\"binding\": \"VECTORIZE\", \"index_name\": \"my-index\"}],\n \"ai\": {\"binding\": \"AI\"},\n \"analytics_engine_datasets\": [{\"binding\": \"ANALYTICS\"}],\n \"vars\": {\"API_URL\": \"https://api.example.com\", \"ENVIRONMENT\": \"production\"},\n \"env\": {\n \"preview\": {\n \"vars\": {\"API_URL\": \"https://staging-api.example.com\"},\n \"kv_namespaces\": [{\"binding\": \"KV\", \"id\": \"preview-namespace-id\"}]\n }\n }\n}\n```\n\n## Build Config\n\n**Git deployment**: Dashboard → Project → Settings → Build settings \nSet build command, output dir, env vars. Framework auto-detection configures automatically.\n\n## Environment Variables\n\n### Local (.dev.vars)\n```bash\n# .dev.vars (never commit)\nSECRET_KEY=\"local-secret-key\"\nAPI_TOKEN=\"dev-token-123\"\n```\n\n### Production\n```bash\necho \"secret-value\" | npx wrangler pages secret put SECRET_KEY --project-name=my-project\nnpx wrangler pages secret list --project-name=my-project\nnpx wrangler pages secret delete SECRET_KEY --project-name=my-project\n```\n\nAccess: `env.SECRET_KEY`\n\n## Static Config Files\n\n### _redirects\nPlace in build output (e.g., `dist/_redirects`):\n\n```txt\n/old-page /new-page 301 # 301 redirect\n/blog/* /news/:splat 301 # Splat wildcard\n/users/:id /members/:id 301 # Placeholders\n/api/* /api-v2/:splat 200 # Proxy (no redirect)\n```\n\n**Limits**: 2,100 total (2,000 static + 100 dynamic), 1,000 char/line \n**Note**: Functions take precedence\n\n### _headers\n```txt\n/secure/*\n X-Frame-Options: DENY\n X-Content-Type-Options: nosniff\n\n/api/*\n Access-Control-Allow-Origin: *\n\n/static/*\n Cache-Control: public, max-age=31536000, immutable\n```\n\n**Limits**: 100 rules, 2,000 char/line \n**Note**: Only static assets; Functions set headers in Response\n\n### _routes.json\nControls which requests invoke Functions (auto-generated for most frameworks):\n\n```json\n{\n \"version\": 1,\n \"include\": [\"/*\"],\n \"exclude\": [\"/build/*\", \"/static/*\", \"/assets/*\", \"/*.{ico,png,jpg,css,js}\"]\n}\n```\n\n**Purpose**: Functions are metered; static requests are free. `exclude` takes precedence. Max 100 rules, 100 char/rule.\n\n## TypeScript\n\n```bash\nnpx wrangler types --path='./functions/types.d.ts'\n```\n\nPoint `types` in `functions/tsconfig.json` to generated file.\n\n## Smart Placement\n\nAutomatically optimizes function execution location based on request patterns.\n\n```jsonc\n{\n \"placement\": {\n \"mode\": \"smart\" // Enable optimization (default: off)\n }\n}\n```\n\n**How it works**: System analyzes traffic over hours/days and places function execution closer to:\n- User clusters (e.g., regional traffic)\n- Data sources (e.g., D1 database primary location)\n\n**Benefits**: \n- Lower latency for read-heavy apps with centralized databases\n- Better performance for apps with regional traffic patterns\n\n**Trade-offs**:\n- Initial learning period: First requests may be slower while system optimizes\n- Optimization time: Performance improves over 24-48 hours\n\n**When to enable**: Global apps with D1/Durable Objects in specific regions, or apps with concentrated geographic traffic.\n\n**When to skip**: Evenly distributed global traffic with no data locality constraints.\n\n## Remote Bindings (Local Dev)\n\nConnect local dev server to production bindings instead of local mocks:\n\n```bash\n# All bindings remote\nnpx wrangler pages dev ./dist --remote\n\n# Specific bindings remote (others local)\nnpx wrangler pages dev ./dist --remote --kv=KV --d1=DB\n```\n\n**Use cases**:\n- Test against production data (read-only operations)\n- Debug binding-specific behavior\n- Validate changes before deployment\n\n**⚠️ Warning**: \n- Writes affect **real production data**\n- Use only for read-heavy debugging or with non-production accounts\n- Consider creating separate preview environments instead\n\n**Requirements**: Must be logged in (`npx wrangler login`) with access to bindings.\n\n## Local Dev\n\n```bash\n# Basic\nnpx wrangler pages dev ./dist\n\n# With bindings\nnpx wrangler pages dev ./dist --kv KV --d1 DB=local-db-id\n\n# Remote bindings (production data)\nnpx wrangler pages dev ./dist --remote\n\n# Persistence\nnpx wrangler pages dev ./dist --persist-to=./.wrangler/state/v3\n\n# Proxy mode (SSR frameworks)\nnpx wrangler pages dev -- npm run dev\n```\n\n## Limits (as of Jan 2026)\n\n| Resource | Free | Paid |\n|----------|------|------|\n| **Functions Requests** | 100k/day | Unlimited (metered) |\n| **Function CPU Time** | 10ms/req | 30ms/req (Workers Paid) |\n| **Function Memory** | 128MB | 128MB |\n| **Script Size** | 1MB compressed | 10MB compressed |\n| **Deployments** | 500/month | 5,000/month |\n| **Files per Deploy** | 20,000 | 20,000 |\n| **File Size** | 25MB | 25MB |\n| **Build Time** | 20min | 20min |\n| **Redirects** | 2,100 (2k static + 100 dynamic) | Same |\n| **Header Rules** | 100 | 100 |\n| **Route Rules** | 100 | 100 |\n| **Subrequests** | 50/request | 1,000/request (Workers Paid) |\n\n**Notes**:\n- Functions use Workers runtime; Workers Paid plan increases limits\n- Free plan sufficient for most projects\n- Static requests always free (not counted toward limits)\n\n[Full limits](https://developers.cloudflare.com/pages/platform/limits/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages/gotchas.md", "content": "# Gotchas\n\n## Functions Not Running\n\n**Problem**: Function endpoints return 404 or don't execute \n**Causes**: `_routes.json` excludes path; wrong file extension (`.jsx`/`.tsx`); Functions dir not at output root \n**Solution**: Check `_routes.json`, rename to `.ts`/`.js`, verify build output structure\n\n## 404 on Static Assets\n\n**Problem**: Static files not serving \n**Causes**: Build output dir misconfigured; Functions catching requests; Advanced mode missing `env.ASSETS.fetch()` \n**Solution**: Verify output dir, add exclusions to `_routes.json`, call `env.ASSETS.fetch()` in `_worker.js`\n\n## Bindings Not Working\n\n**Problem**: `env.BINDING` undefined or errors \n**Causes**: wrangler.jsonc syntax error; wrong binding IDs; missing `.dev.vars`; out-of-sync types \n**Solution**: Validate config, verify IDs, create `.dev.vars`, run `npx wrangler types`\n\n## Build Failures\n\n**Problem**: Deployment fails during build \n**Causes**: Wrong build command/output dir; Node version incompatibility; missing env vars; 20min timeout; OOM \n**Solution**: Check Dashboard → Deployments → Build log; verify settings; add `.nvmrc`; optimize build\n\n## Middleware Not Running\n\n**Problem**: Middleware doesn't execute \n**Causes**: Wrong filename (not `_middleware.ts`); missing `onRequest` export; didn't call `next()` \n**Solution**: Rename file with underscore prefix; export handler; call `next()` or return Response\n\n## Headers/Redirects Not Working\n\n**Problem**: `_headers` or `_redirects` not applying \n**Causes**: Only work for static assets; Functions override; syntax errors; exceeded limits \n**Solution**: Set headers in Response object for Functions; verify syntax; check limits (100 headers, 2,100 redirects)\n\n## TypeScript Errors\n\n**Problem**: Type errors in Functions code \n**Causes**: Types not generated; Env interface doesn't match wrangler.jsonc \n**Solution**: Run `npx wrangler types --path='./functions/types.d.ts'`; update Env interface\n\n## Local Dev Issues\n\n**Problem**: Dev server errors or bindings don't work \n**Causes**: Port conflict; bindings not passed; local vs HTTPS differences \n**Solution**: Use `--port=3000`; pass bindings via CLI or wrangler.jsonc; account for HTTP/HTTPS differences\n\n## Performance Issues\n\n**Problem**: Slow responses or CPU limit errors \n**Causes**: Functions invoked for static assets; cold starts; 10ms CPU limit; large bundle \n**Solution**: Exclude static via `_routes.json`; optimize hot paths; keep bundle < 1MB\n\n## Framework-Specific\n\n### ⚠️ Deprecated Frameworks\n\n**Next.js**: Official adapter (`@cloudflare/next-on-pages`) **deprecated** and unmaintained.\n- **Problem**: No updates since 2024; incompatible with Next.js 15+; missing App Router features\n- **Cause**: Cloudflare discontinued official support; community fork exists but limited\n- **Solutions**:\n 1. **Recommended**: Use Vercel (official Next.js host)\n 2. **Advanced**: Self-host on Workers using custom adapter (complex, unsupported)\n 3. **Migration**: Switch to SvelteKit/Nuxt (similar DX, full Pages support)\n\n**Remix**: Official adapter (`@remix-run/cloudflare-pages`) **deprecated**.\n- **Problem**: No maintenance from Remix team; compatibility issues with Remix v2+\n- **Cause**: Remix team deprecated all framework adapters\n- **Solutions**:\n 1. **Recommended**: Migrate to SvelteKit (similar file-based routing, better DX)\n 2. **Alternative**: Use Astro (static-first with optional SSR)\n 3. **Workaround**: Continue using deprecated adapter (no future support)\n\n### ✅ Supported Frameworks\n\n**SvelteKit**:\n- Use `@sveltejs/adapter-cloudflare`\n- Access bindings via `platform.env` in server load functions\n- Set `platform: 'cloudflare'` in `svelte.config.js`\n\n**Astro**:\n- Built-in Cloudflare adapter\n- Access bindings via `Astro.locals.runtime.env`\n\n**Nuxt**:\n- Set `nitro.preset: 'cloudflare-pages'` in `nuxt.config.ts`\n- Access bindings via `event.context.cloudflare.env`\n\n**Qwik, Solid Start**:\n- Built-in or official Cloudflare adapters available\n- Check respective framework docs for binding access\n\n## Debugging\n\n```typescript\n// Log request details\nconsole.log('Request:', { method: request.method, url: request.url });\nconsole.log('Env:', Object.keys(env));\nconsole.log('Params:', params);\n```\n\n**View logs**: `npx wrangler pages deployment tail --project-name=my-project`\n\n## Smart Placement Issues\n\n### Increased Cold Start Latency\n\n**Problem**: First requests slower after enabling Smart Placement \n**Cause**: Initial optimization period while system learns traffic patterns \n**Solution**: Expected behavior during first 24-48 hours; monitor latency trends over time\n\n### Inconsistent Response Times\n\n**Problem**: Latency varies significantly across requests during initial deployment \n**Cause**: Smart Placement testing different execution locations to find optimal placement \n**Solution**: Normal during learning phase; stabilizes after traffic patterns emerge (1-2 days)\n\n### No Performance Improvement\n\n**Problem**: Smart Placement enabled but no latency reduction observed \n**Cause**: Traffic evenly distributed globally, or no data locality constraints \n**Solution**: Smart Placement most effective with centralized data (D1/DO) or regional traffic; disable if no benefit\n\n## Remote Bindings Issues\n\n### Accidentally Modified Production Data\n\n**Problem**: Local dev with `--remote` altered production database/KV \n**Cause**: Remote bindings connect directly to production resources; writes are real \n**Solution**: \n- Use `--remote` only for read-heavy debugging\n- Create separate preview environments for testing\n- Never use `--remote` for write operations during development\n\n### Remote Binding Auth Errors\n\n**Problem**: `npx wrangler pages dev --remote` fails with \"Unauthorized\" or auth error \n**Cause**: Not logged in, session expired, or insufficient account permissions \n**Solution**: \n1. Run `npx wrangler login` to re-authenticate\n2. Verify account has access to project and bindings\n3. Check binding IDs match production configuration\n\n### Slow Local Dev with Remote Bindings\n\n**Problem**: Local dev server slow when using `--remote` \n**Cause**: Every request makes network calls to production bindings \n**Solution**: Use local bindings for development; reserve `--remote` for final validation\n\n## Common Errors\n\n### \"Module not found\"\n**Cause**: Dependencies not bundled or build output incorrect \n**Solution**: Check build output directory, ensure dependencies bundled\n\n### \"Binding not found\"\n**Cause**: Binding not configured or types out of sync \n**Solution**: Verify wrangler.jsonc, run `npx wrangler types`\n\n### \"Request exceeded CPU limit\"\n**Cause**: Code execution too slow or heavy compute \n**Solution**: Optimize hot paths, upgrade to Workers Paid\n\n### \"Script too large\"\n**Cause**: Bundle size exceeds limit \n**Solution**: Tree-shake, use dynamic imports, code-split\n\n### \"Too many subrequests\"\n**Cause**: Exceeded 50 subrequest limit \n**Solution**: Batch or reduce fetch calls\n\n### \"KV key not found\"\n**Cause**: Key doesn't exist or wrong namespace \n**Solution**: Check namespace matches environment\n\n### \"D1 error\"\n**Cause**: Wrong database_id or missing migrations \n**Solution**: Verify config, run `wrangler d1 migrations list`\n\n## Limits Reference (Jan 2026)\n\n| Resource | Free | Paid |\n|----------|------|------|\n| Functions Requests | 100k/day | Unlimited |\n| CPU Time | 10ms/req | 30ms/req |\n| Memory | 128MB | 128MB |\n| Script Size | 1MB | 10MB |\n| Subrequests | 50/req | 1,000/req |\n| Deployments | 500/month | 5,000/month |\n\n**Tip**: Hitting CPU limit? Optimize hot paths or upgrade to Workers Paid plan.\n\n[Full limits](https://developers.cloudflare.com/pages/platform/limits/)\n\n## Getting Help\n\n1. Check [Pages Docs](https://developers.cloudflare.com/pages/)\n2. Search [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)\n3. Review [Workers Examples](https://developers.cloudflare.com/workers/examples/)\n4. Check framework-specific docs/adapters\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages/patterns.md", "content": "# Patterns\n\n## API Routes\n\n```typescript\n// functions/api/todos/[id].ts\nexport const onRequestGet: PagesFunction = async ({ env, params }) => {\n const todo = await env.DB.prepare('SELECT * FROM todos WHERE id = ?').bind(params.id).first();\n if (!todo) return new Response('Not found', { status: 404 });\n return Response.json(todo);\n};\n\nexport const onRequestPut: PagesFunction = async ({ env, params, request }) => {\n const body = await request.json();\n await env.DB.prepare('UPDATE todos SET title = ?, completed = ? WHERE id = ?')\n .bind(body.title, body.completed, params.id).run();\n return Response.json({ success: true });\n};\n// Also: onRequestDelete, onRequestPost\n```\n\n## Auth Middleware\n\n```typescript\n// functions/_middleware.ts\nconst auth: PagesFunction = async (context) => {\n if (context.request.url.includes('/public/')) return context.next();\n const authHeader = context.request.headers.get('Authorization');\n if (!authHeader?.startsWith('Bearer ')) {\n return new Response('Unauthorized', { status: 401 });\n }\n \n try {\n const payload = await verifyJWT(authHeader.substring(7), context.env.JWT_SECRET);\n context.data.user = payload;\n return context.next();\n } catch (err) {\n return new Response('Invalid token', { status: 401 });\n }\n};\nexport const onRequest = [auth];\n```\n\n## CORS\n\n```typescript\n// functions/api/_middleware.ts\nconst corsHeaders = {\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',\n 'Access-Control-Allow-Headers': 'Content-Type, Authorization'\n};\n\nexport const onRequest: PagesFunction = async (context) => {\n if (context.request.method === 'OPTIONS') {\n return new Response(null, {headers: corsHeaders});\n }\n const response = await context.next();\n Object.entries(corsHeaders).forEach(([k, v]) => response.headers.set(k, v));\n return response;\n};\n```\n\n## Form Handling\n\n```typescript\n// functions/api/contact.ts\nexport const onRequestPost: PagesFunction = async ({ request, env }) => {\n const formData = await request.formData();\n await env.QUEUE.send({name: formData.get('name'), email: formData.get('email')});\n return new Response('

Thanks!

', { headers: { 'Content-Type': 'text/html' } });\n};\n```\n\n## Background Tasks\n\n```typescript\nexport const onRequestPost: PagesFunction = async ({ request, waitUntil }) => {\n const data = await request.json();\n waitUntil(fetch('https://api.example.com/webhook', {\n method: 'POST', body: JSON.stringify(data)\n }));\n return Response.json({ queued: true });\n};\n```\n\n## Error Handling\n\n```typescript\n// functions/_middleware.ts\nconst errorHandler: PagesFunction = async (context) => {\n try {\n return await context.next();\n } catch (error) {\n console.error('Error:', error);\n if (context.request.url.includes('/api/')) {\n return Response.json({ error: error.message }, { status: 500 });\n }\n return new Response(`

Error

${error.message}

`, { \n status: 500, headers: { 'Content-Type': 'text/html' } \n });\n }\n};\nexport const onRequest = [errorHandler];\n```\n\n## Caching\n\n```typescript\n// functions/api/data.ts\nexport const onRequestGet: PagesFunction = async ({ env, request }) => {\n const cacheKey = `data:${new URL(request.url).pathname}`;\n const cached = await env.KV.get(cacheKey, 'json');\n if (cached) return Response.json(cached, { headers: { 'X-Cache': 'HIT' } });\n \n const data = await env.DB.prepare('SELECT * FROM data').first();\n await env.KV.put(cacheKey, JSON.stringify(data), {expirationTtl: 3600});\n return Response.json(data, {headers: {'X-Cache': 'MISS'}});\n};\n```\n\n## Smart Placement for Database Apps\n\nEnable Smart Placement for apps with D1 or centralized data sources:\n\n```jsonc\n// wrangler.jsonc\n{\n \"name\": \"global-app\",\n \"placement\": {\n \"mode\": \"smart\"\n },\n \"d1_databases\": [{\n \"binding\": \"DB\",\n \"database_id\": \"your-db-id\"\n }]\n}\n```\n\n```typescript\n// functions/api/data.ts\nexport const onRequestGet: PagesFunction = async ({ env }) => {\n // Smart Placement optimizes execution location over time\n // Balances user location vs database location\n const data = await env.DB.prepare('SELECT * FROM products LIMIT 10').all();\n return Response.json(data);\n};\n```\n\n**Best for**: Read-heavy apps with D1/Durable Objects in specific regions. \n**Not needed**: Apps without data locality constraints or with evenly distributed traffic.\n\n## Framework Integration\n\n**Supported** (2026): SvelteKit, Astro, Nuxt, Qwik, Solid Start\n\n```bash\nnpm create cloudflare@latest my-app -- --framework=svelte\n```\n\n### SvelteKit\n```typescript\n// src/routes/+page.server.ts\nexport const load = async ({ platform }) => {\n const todos = await platform.env.DB.prepare('SELECT * FROM todos').all();\n return { todos: todos.results };\n};\n```\n\n### Astro\n```astro\n---\nconst { DB } = Astro.locals.runtime.env;\nconst todos = await DB.prepare('SELECT * FROM todos').all();\n---\n
    {todos.results.map(t =>
  • {t.title}
    • )}
\n```\n\n### Nuxt\n```typescript\n// server/api/todos.get.ts\nexport default defineEventHandler(async (event) => {\n const { DB } = event.context.cloudflare.env;\n return await DB.prepare('SELECT * FROM todos').all();\n});\n```\n\n**⚠️ Framework Status** (2026):\n- ✅ **Supported**: SvelteKit, Astro, Nuxt, Qwik, Solid Start\n- ❌ **Deprecated**: Next.js (`@cloudflare/next-on-pages`), Remix (`@remix-run/cloudflare-pages`)\n\nFor deprecated frameworks, see [gotchas.md](./gotchas.md#framework-specific) for migration options.\n\n[Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)\n\n## Monorepo\n\nDashboard → Settings → Build → Root directory. Set to subproject (e.g., `apps/web`).\n\n## Best Practices\n\n**Performance**: Exclude static via `_routes.json`; cache with KV; keep bundle < 1MB \n**Security**: Use secrets (not vars); validate inputs; rate limit with KV/DO \n**Workflow**: Preview per branch; local dev with `wrangler pages dev`; instant rollbacks in Dashboard\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages-functions/README.md", "content": "# Cloudflare Pages Functions\n\nServerless functions on Cloudflare Pages using Workers runtime. Full-stack dev with file-based routing.\n\n## Quick Navigation\n\n**Need to...**\n| Task | Go to |\n|------|-------|\n| Set up TypeScript types | [configuration.md](./configuration.md) - TypeScript Setup |\n| Configure bindings (KV, D1, R2) | [configuration.md](./configuration.md) - wrangler.jsonc |\n| Access request/env/params | [api.md](./api.md) - EventContext |\n| Add middleware or auth | [patterns.md](./patterns.md) - Middleware, Auth |\n| Background tasks (waitUntil) | [patterns.md](./patterns.md) - Background Tasks |\n| Debug errors or check limits | [gotchas.md](./gotchas.md) - Common Errors, Limits |\n\n## Decision Tree: Is This Pages Functions?\n\n```\nNeed serverless backend? \n├─ Yes, for a static site → Pages Functions\n├─ Yes, standalone API → Workers\n└─ Just static hosting → Pages (no functions)\n\nHave existing Worker?\n├─ Complex routing logic → Use _worker.js (Advanced Mode)\n└─ Simple routes → Migrate to /functions (File-Based)\n\nFramework-based?\n├─ Next.js/SvelteKit/Remix → Uses _worker.js automatically\n└─ Vanilla/HTML/React SPA → Use /functions\n```\n\n## File-Based Routing\n\n```\n/functions\n ├── index.js → /\n ├── api.js → /api\n ├── users/\n │ ├── index.js → /users/\n │ ├── [user].js → /users/:user\n │ └── [[catchall]].js → /users/*\n └── _middleware.js → runs on all routes\n```\n\n**Rules:**\n- `index.js` → directory root\n- Trailing slash optional\n- Specific routes precede catch-alls\n- Falls back to static if no match\n\n## Dynamic Routes\n\n**Single segment** `[param]` → string:\n```js\n// /functions/users/[user].js\nexport function onRequest(context) {\n return new Response(`Hello ${context.params.user}`);\n}\n// Matches: /users/nevi\n```\n\n**Multi-segment** `[[param]]` → array:\n```js\n// /functions/users/[[catchall]].js\nexport function onRequest(context) {\n return new Response(JSON.stringify(context.params.catchall));\n}\n// Matches: /users/nevi/foobar → [\"nevi\", \"foobar\"]\n```\n\n## Key Features\n\n- **Method handlers:** `onRequestGet`, `onRequestPost`, etc.\n- **Middleware:** `_middleware.js` for cross-cutting concerns\n- **Bindings:** KV, D1, R2, Durable Objects, Workers AI, Service bindings\n- **TypeScript:** Full type support via `wrangler types` command\n- **Advanced mode:** Use `_worker.js` for custom routing logic\n\n## Reading Order\n\n**New to Pages Functions?** Start here:\n1. [README.md](./README.md) - Overview, routing, decision tree (you are here)\n2. [configuration.md](./configuration.md) - TypeScript setup, wrangler.jsonc, bindings\n3. [api.md](./api.md) - EventContext, handlers, bindings reference\n4. [patterns.md](./patterns.md) - Middleware, auth, CORS, rate limiting, caching\n5. [gotchas.md](./gotchas.md) - Common errors, debugging, limits\n\n**Quick reference lookup:**\n- Bindings table → [api.md](./api.md)\n- Error diagnosis → [gotchas.md](./gotchas.md)\n- TypeScript setup → [configuration.md](./configuration.md)\n\n## See Also\n- [pages](../pages/) - Pages platform overview and static site deployment\n- [workers](../workers/) - Workers runtime API reference\n- [d1](../d1/) - D1 database integration with Pages Functions\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages-functions/api.md", "content": "# Function API\n\n## EventContext\n\n```typescript\ninterface EventContext {\n request: Request; // Incoming request\n functionPath: string; // Request path\n waitUntil(promise: Promise): void; // Background tasks (non-blocking)\n passThroughOnException(): void; // Fallback to static on error\n next(input?: Request | string, init?: RequestInit): Promise;\n env: Env; // Bindings, vars, secrets\n params: Record; // Route params ([user] or [[catchall]])\n data: any; // Middleware shared state\n}\n```\n\n**TypeScript:** See [configuration.md](./configuration.md) for `wrangler types` setup\n\n## Handlers\n\n```typescript\n// Generic (fallback for any method)\nexport async function onRequest(ctx: EventContext): Promise {\n return new Response('Any method');\n}\n\n// Method-specific (takes precedence over generic)\nexport async function onRequestGet(ctx: EventContext): Promise {\n return Response.json({ message: 'GET' });\n}\n\nexport async function onRequestPost(ctx: EventContext): Promise {\n const body = await ctx.request.json();\n return Response.json({ received: body });\n}\n// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions\n```\n\n## Bindings Reference\n\n| Binding Type | Interface | Config Key | Use Case |\n|--------------|-----------|------------|----------|\n| KV | `KVNamespace` | `kv_namespaces` | Key-value cache, sessions, config |\n| D1 | `D1Database` | `d1_databases` | Relational data, SQL queries |\n| R2 | `R2Bucket` | `r2_buckets` | Large files, user uploads, assets |\n| Durable Objects | `DurableObjectNamespace` | `durable_objects.bindings` | Stateful coordination, websockets |\n| Workers AI | `Ai` | `ai.binding` | LLM inference, embeddings |\n| Vectorize | `VectorizeIndex` | `vectorize` | Vector search, embeddings |\n| Service Binding | `Fetcher` | `services` | Worker-to-worker RPC |\n| Analytics Engine | `AnalyticsEngineDataset` | `analytics_engine_datasets` | Event logging, metrics |\n| Environment Vars | `string` | `vars` | Non-sensitive config |\n\nSee [configuration.md](./configuration.md) for wrangler.jsonc examples.\n\n## Bindings\n\n### KV\n\n```typescript\ninterface Env { KV: KVNamespace; }\nexport const onRequest: PagesFunction = async (ctx) => {\n await ctx.env.KV.put('key', 'value', { expirationTtl: 3600 });\n const val = await ctx.env.KV.get('key', { type: 'json' });\n const keys = await ctx.env.KV.list({ prefix: 'user:' });\n return Response.json({ val });\n};\n```\n\n### D1\n\n```typescript\ninterface Env { DB: D1Database; }\nexport const onRequest: PagesFunction = async (ctx) => {\n const user = await ctx.env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(123).first();\n return Response.json(user);\n};\n```\n\n### R2\n\n```typescript\ninterface Env { BUCKET: R2Bucket; }\nexport const onRequest: PagesFunction = async (ctx) => {\n const obj = await ctx.env.BUCKET.get('file.txt');\n if (!obj) return new Response('Not found', { status: 404 });\n await ctx.env.BUCKET.put('file.txt', ctx.request.body);\n return new Response(obj.body);\n};\n```\n\n### Durable Objects\n\n```typescript\ninterface Env { COUNTER: DurableObjectNamespace; }\nexport const onRequest: PagesFunction = async (ctx) => {\n const stub = ctx.env.COUNTER.get(ctx.env.COUNTER.idFromName('global'));\n return stub.fetch(ctx.request);\n};\n```\n\n### Workers AI\n\n```typescript\ninterface Env { AI: Ai; }\nexport const onRequest: PagesFunction = async (ctx) => {\n const resp = await ctx.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });\n return Response.json(resp);\n};\n```\n\n### Service Bindings & Env Vars\n\n```typescript\ninterface Env { AUTH: Fetcher; API_KEY: string; }\nexport const onRequest: PagesFunction = async (ctx) => {\n // Service binding: forward to another Worker\n return ctx.env.AUTH.fetch(ctx.request);\n \n // Environment variable\n return Response.json({ key: ctx.env.API_KEY });\n};\n```\n\n## Advanced Mode (env.ASSETS)\n\nWhen using `_worker.js`, access static assets via `env.ASSETS.fetch()`:\n\n```typescript\ninterface Env { ASSETS: Fetcher; KV: KVNamespace; }\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname.startsWith('/api/')) {\n return Response.json({ data: await env.KV.get('key') });\n }\n return env.ASSETS.fetch(request); // Fallback to static\n }\n} satisfies ExportedHandler;\n```\n\n**See also:** [configuration.md](./configuration.md) for TypeScript setup and wrangler.jsonc | [patterns.md](./patterns.md) for middleware and auth patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages-functions/configuration.md", "content": "# Configuration\n\n## TypeScript Setup\n\n**Generate types from wrangler.jsonc** (replaces deprecated `@cloudflare/workers-types`):\n\n```bash\nnpx wrangler types\n```\n\nCreates `worker-configuration.d.ts` with typed `Env` interface based on your bindings.\n\n```typescript\n// functions/api.ts\nexport const onRequest: PagesFunction = async (ctx) => {\n // ctx.env.KV, ctx.env.DB, etc. are fully typed\n return Response.json({ ok: true });\n};\n```\n\n**Manual types** (if not using wrangler types):\n\n```typescript\ninterface Env {\n KV: KVNamespace;\n DB: D1Database;\n API_KEY: string;\n}\nexport const onRequest: PagesFunction = async (ctx) => { /* ... */ };\n```\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"name\": \"my-pages-app\",\n \"pages_build_output_dir\": \"./dist\",\n \"compatibility_date\": \"2025-01-01\",\n \"compatibility_flags\": [\"nodejs_compat\"],\n \n \"vars\": { \"API_URL\": \"https://api.example.com\" },\n \"kv_namespaces\": [{ \"binding\": \"KV\", \"id\": \"abc123\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"prod-db\", \"database_id\": \"xyz789\" }],\n \"r2_buckets\": [{ \"binding\": \"BUCKET\", \"bucket_name\": \"my-bucket\" }],\n \"durable_objects\": { \"bindings\": [{ \"name\": \"COUNTER\", \"class_name\": \"Counter\", \"script_name\": \"counter-worker\" }] },\n \"services\": [{ \"binding\": \"AUTH\", \"service\": \"auth-worker\" }],\n \"ai\": { \"binding\": \"AI\" },\n \"vectorize\": [{ \"binding\": \"VECTORIZE\", \"index_name\": \"my-index\" }],\n \"analytics_engine_datasets\": [{ \"binding\": \"ANALYTICS\" }]\n}\n```\n\n## Environment Overrides\n\nTop-level → local dev, `env.preview` → preview, `env.production` → production\n\n```jsonc\n{\n \"vars\": { \"API_URL\": \"http://localhost:8787\" },\n \"env\": {\n \"production\": { \"vars\": { \"API_URL\": \"https://api.example.com\" } }\n }\n}\n```\n\n**Note:** If overriding `vars`, `kv_namespaces`, `d1_databases`, etc., ALL must be redefined (non-inheritable)\n\n## Local Secrets (.dev.vars)\n\n**Local dev only** - NOT deployed:\n\n```bash\n# .dev.vars (add to .gitignore)\nSECRET_KEY=\"my-secret-value\"\n```\n\nAccessed via `ctx.env.SECRET_KEY`. Set production secrets:\n```bash\necho \"value\" | npx wrangler pages secret put SECRET_KEY --project-name=my-app\n```\n\n## Static Config Files\n\n**_routes.json** - Custom routing:\n```json\n{ \"version\": 1, \"include\": [\"/api/*\"], \"exclude\": [\"/static/*\"] }\n```\n\n**_headers** - Static headers:\n```\n/static/*\n Cache-Control: public, max-age=31536000\n```\n\n**_redirects** - Redirects:\n```\n/old /new 301\n```\n\n## Local Dev & Deployment\n\n```bash\n# Dev server\nnpx wrangler pages dev ./dist\n\n# With bindings\nnpx wrangler pages dev ./dist --kv=KV --d1=DB=db-id --r2=BUCKET\n\n# Durable Objects (2 terminals)\ncd do-worker && npx wrangler dev\ncd pages-project && npx wrangler pages dev ./dist --do COUNTER=Counter@do-worker\n\n# Deploy\nnpx wrangler pages deploy ./dist\nnpx wrangler pages deploy ./dist --branch preview\n\n# Download config\nnpx wrangler pages download config my-project\n```\n\n**See also:** [api.md](./api.md) for binding usage examples\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages-functions/gotchas.md", "content": "# Gotchas & Debugging\n\n## Error Diagnosis\n\n| Symptom | Likely Cause | Solution |\n|---------|--------------|----------|\n| **Function not invoking** | Wrong `/functions` location, wrong extension, or `_routes.json` excludes path | Check `pages_build_output_dir`, use `.js`/`.ts`, verify `_routes.json` |\n| **`ctx.env.BINDING` undefined** | Binding not configured or name mismatch | Add to `wrangler.jsonc`, verify exact name (case-sensitive), redeploy |\n| **TypeScript errors on `ctx.env`** | Missing type definition | Run `wrangler types` or define `interface Env {}` |\n| **Middleware not running** | Wrong filename/location or missing `ctx.next()` | Name exactly `_middleware.js`, export `onRequest`, call `ctx.next()` |\n| **Secrets missing in production** | `.dev.vars` not deployed | `.dev.vars` is local only - set production secrets via dashboard or `wrangler secret put` |\n| **Type mismatch on binding** | Wrong interface type | See [api.md](./api.md) bindings table for correct types |\n| **\"KV key not found\" but exists** | Key in wrong namespace or env | Verify namespace binding, check preview vs production env |\n| **Function times out** | Synchronous wait or missing `await` | All I/O must be async/await, use `ctx.waitUntil()` for background tasks |\n\n## Common Errors\n\n### TypeScript type errors\n\n**Problem:** `ctx.env.MY_BINDING` shows type error \n**Cause:** No type definition for `Env` \n**Solution:** Run `npx wrangler types` or manually define:\n```typescript\ninterface Env { MY_BINDING: KVNamespace; }\nexport const onRequest: PagesFunction = async (ctx) => { /* ... */ };\n```\n\n### Secrets not available in production\n\n**Problem:** `ctx.env.SECRET_KEY` is undefined in production \n**Cause:** `.dev.vars` is local-only, not deployed \n**Solution:** Set production secrets:\n```bash\necho \"value\" | npx wrangler pages secret put SECRET_KEY --project-name=my-app\n```\n\n## Debugging\n\n```typescript\n// Console logging\nexport async function onRequest(ctx) {\n console.log('Request:', ctx.request.method, ctx.request.url);\n const res = await ctx.next();\n console.log('Status:', res.status);\n return res;\n}\n```\n\n```bash\n# Stream real-time logs\nnpx wrangler pages deployment tail\nnpx wrangler pages deployment tail --status error\n```\n\n```jsonc\n// Source maps (wrangler.jsonc)\n{ \"upload_source_maps\": true }\n```\n\n## Limits\n\n| Resource | Free | Paid |\n|----------|------|------|\n| CPU time | 10ms | 50ms |\n| Memory | 128 MB | 128 MB |\n| Script size | 10 MB compressed | 10 MB compressed |\n| Env vars | 5 KB per var, 64 max | 5 KB per var, 64 max |\n| Requests | 100k/day | Unlimited ($0.50/million) |\n\n## Best Practices\n\n**Performance:** Minimize deps (cold start), use KV for cache/D1 for relational/R2 for large files, set `Cache-Control` headers, batch DB ops, handle errors gracefully\n\n**Security:** Never commit secrets (use `.dev.vars` + gitignore), validate input, sanitize before DB, implement auth middleware, set CORS headers, rate limit per-IP\n\n## Migration\n\n**Workers → Pages Functions:**\n- `export default { fetch(req, env) {} }` → `export function onRequest(ctx) { const { request, env } = ctx; }`\n- Use `_worker.js` for complex routing: `env.ASSETS.fetch(request)` for static files\n\n**Other platforms → Pages:**\n- File-based routing: `/functions/api/users.js` → `/api/users`\n- Dynamic routes: `[param]` not `:param`\n- Replace Node.js deps with Workers APIs or add `nodejs_compat` flag\n\n## Resources\n\n- [Official Docs](https://developers.cloudflare.com/pages/functions/)\n- [Workers APIs](https://developers.cloudflare.com/workers/runtime-apis/)\n- [Examples](https://github.com/cloudflare/pages-example-projects)\n- [Discord](https://discord.gg/cloudflaredev)\n\n**See also:** [configuration.md](./configuration.md) for TypeScript setup | [patterns.md](./patterns.md) for middleware/auth | [api.md](./api.md) for bindings\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pages-functions/patterns.md", "content": "# Common Patterns\n\n## Background Tasks (waitUntil)\n\nNon-blocking tasks after response sent (analytics, cleanup, webhooks):\n\n```typescript\nexport async function onRequest(ctx: EventContext) {\n const res = Response.json({ success: true });\n \n ctx.waitUntil(ctx.env.KV.put('last-visit', new Date().toISOString()));\n ctx.waitUntil(Promise.all([\n ctx.env.ANALYTICS.writeDataPoint({ event: 'view' }),\n fetch('https://webhook.site/...', { method: 'POST' })\n ]));\n \n return res; // Returned immediately\n}\n```\n\n## Middleware & Auth\n\n```typescript\n// functions/_middleware.js (global) or functions/users/_middleware.js (scoped)\nexport async function onRequest(ctx) {\n try { return await ctx.next(); } \n catch (err) { return new Response(err.message, { status: 500 }); }\n}\n\n// Chained: export const onRequest = [errorHandler, auth, logger];\n\n// Auth\nasync function auth(ctx: EventContext) {\n const token = ctx.request.headers.get('authorization')?.replace('Bearer ', '');\n if (!token) return new Response('Unauthorized', { status: 401 });\n const session = await ctx.env.KV.get(`session:${token}`);\n if (!session) return new Response('Invalid', { status: 401 });\n ctx.data.user = JSON.parse(session);\n return ctx.next();\n}\n```\n\n## CORS & Rate Limiting\n\n```typescript\n// CORS middleware\nconst cors = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST' };\nexport async function onRequestOptions() { return new Response(null, { headers: cors }); }\nexport async function onRequest(ctx) {\n const res = await ctx.next();\n Object.entries(cors).forEach(([k, v]) => res.headers.set(k, v));\n return res;\n}\n\n// Rate limiting (KV-based)\nasync function rateLimit(ctx: EventContext) {\n const ip = ctx.request.headers.get('CF-Connecting-IP') || 'unknown';\n const count = parseInt(await ctx.env.KV.get(`rate:${ip}`) || '0');\n if (count >= 100) return new Response('Rate limited', { status: 429 });\n await ctx.env.KV.put(`rate:${ip}`, (count + 1).toString(), { expirationTtl: 3600 });\n return ctx.next();\n}\n```\n\n## Forms, Caching, Redirects\n\n```typescript\n// JSON & file upload\nexport async function onRequestPost(ctx) {\n const ct = ctx.request.headers.get('content-type') || '';\n if (ct.includes('application/json')) return Response.json(await ctx.request.json());\n if (ct.includes('multipart/form-data')) {\n const file = (await ctx.request.formData()).get('file') as File;\n await ctx.env.BUCKET.put(file.name, file.stream());\n return Response.json({ uploaded: file.name });\n }\n}\n\n// Cache API\nexport async function onRequest(ctx) {\n let res = await caches.default.match(ctx.request);\n if (!res) {\n res = new Response('Data');\n res.headers.set('Cache-Control', 'public, max-age=3600');\n ctx.waitUntil(caches.default.put(ctx.request, res.clone()));\n }\n return res;\n}\n\n// Redirects\nexport async function onRequest(ctx) {\n if (new URL(ctx.request.url).pathname === '/old') {\n return Response.redirect(new URL('/new', ctx.request.url), 301);\n }\n return ctx.next();\n}\n```\n\n## Testing\n\n**Unit tests** (Vitest + cloudflare:test):\n```typescript\nimport { env } from 'cloudflare:test';\nimport { it, expect } from 'vitest';\nimport { onRequest } from '../functions/api';\n\nit('returns JSON', async () => {\n const req = new Request('http://localhost/api');\n const ctx = { request: req, env, params: {}, data: {} } as EventContext;\n const res = await onRequest(ctx);\n expect(res.status).toBe(200);\n});\n```\n\n**Integration:** `wrangler pages dev` + Playwright/Cypress\n\n## Advanced Mode (_worker.js)\n\nUse `_worker.js` for complex routing (replaces `/functions`):\n\n```typescript\ninterface Env { ASSETS: Fetcher; KV: KVNamespace; }\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname.startsWith('/api/')) {\n return Response.json({ data: await env.KV.get('key') });\n }\n return env.ASSETS.fetch(request); // Static files\n }\n} satisfies ExportedHandler;\n```\n\n**When:** Existing Worker, framework-generated (Next.js/SvelteKit), custom routing logic\n\n**See also:** [api.md](./api.md) for `env.ASSETS.fetch()` | [gotchas.md](./gotchas.md) for debugging\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pipelines/README.md", "content": "# Cloudflare Pipelines\n\nETL streaming platform for ingesting, transforming, and loading data into R2 with SQL transformations.\n\n## Overview\n\nPipelines provides:\n- **Streams**: Durable event buffers (HTTP/Workers ingestion)\n- **Pipelines**: SQL-based transformations\n- **Sinks**: R2 destinations (Iceberg tables or Parquet/JSON files)\n\n**Status**: Open beta (Workers Paid plan) \n**Pricing**: No charge beyond standard R2 storage/operations\n\n## Architecture\n\n```\nData Sources → Streams → Pipelines (SQL) → Sinks → R2\n ↑ ↓ ↓\n HTTP/Workers Transform Iceberg/Parquet\n```\n\n| Component | Purpose | Key Feature |\n|-----------|---------|-------------|\n| Streams | Event ingestion | Structured (validated) or unstructured |\n| Pipelines | Transform with SQL | Immutable after creation |\n| Sinks | Write to R2 | Exactly-once delivery |\n\n## Quick Start\n\n```bash\n# Interactive setup (recommended)\nnpx wrangler pipelines setup\n```\n\n**Minimal Worker example:**\n```typescript\ninterface Env {\n STREAM: Pipeline;\n}\n\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const event = { user_id: \"123\", event_type: \"purchase\", amount: 29.99 };\n \n // Fire-and-forget pattern\n ctx.waitUntil(env.STREAM.send([event]));\n \n return new Response('OK');\n }\n} satisfies ExportedHandler;\n```\n\n## Which Sink Type?\n\n```\nNeed SQL queries on data?\n → R2 Data Catalog (Iceberg)\n ✅ ACID transactions, time-travel, schema evolution\n ❌ More setup complexity (namespace, table, catalog token)\n\nJust file storage/archival?\n → R2 Storage (Parquet)\n ✅ Simple, direct file access\n ❌ No built-in SQL queries\n\nUsing external tools (Spark/Athena)?\n → R2 Storage (Parquet with partitioning)\n ✅ Standard format, partition pruning for performance\n ❌ Must manage schema compatibility yourself\n```\n\n## Common Use Cases\n\n- **Analytics pipelines**: Clickstream, telemetry, server logs\n- **Data warehousing**: ETL into queryable Iceberg tables\n- **Event processing**: Mobile/IoT with enrichment\n- **Ecommerce analytics**: User events, purchases, views\n\n## Reading Order\n\n**New to Pipelines?** Start here:\n1. [configuration.md](./configuration.md) - Setup streams, sinks, pipelines\n2. [api.md](./api.md) - Send events, TypeScript types, SQL functions\n3. [patterns.md](./patterns.md) - Best practices, integrations, complete example\n4. [gotchas.md](./gotchas.md) - Critical warnings, troubleshooting\n\n**Task-based routing:**\n- Setup pipeline → [configuration.md](./configuration.md)\n- Send/query data → [api.md](./api.md)\n- Implement pattern → [patterns.md](./patterns.md)\n- Debug issue → [gotchas.md](./gotchas.md)\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc bindings, schema definition, sink options, CLI commands\n- [api.md](./api.md) - Pipeline binding interface, send() method, HTTP ingest, SQL function reference\n- [patterns.md](./patterns.md) - Fire-and-forget, schema validation with Zod, integrations, performance tuning\n- [gotchas.md](./gotchas.md) - Silent validation failures, immutable pipelines, latency expectations, limits\n\n## See Also\n\n- [r2](../r2/) - R2 storage backend for sinks\n- [queues](../queues/) - Compare with Queues for async processing\n- [workers](../workers/) - Worker runtime for event ingestion\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pipelines/api.md", "content": "# Pipelines API Reference\n\n## Pipeline Binding Interface\n\n```typescript\n// From @cloudflare/workers-types\ninterface Pipeline {\n send(data: object | object[]): Promise;\n}\n\ninterface Env {\n STREAM: Pipeline;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // send() returns Promise - no result data\n await env.STREAM.send([event]);\n return new Response('OK');\n }\n} satisfies ExportedHandler;\n```\n\n**Key points:**\n- `send()` accepts single object or array\n- Always returns `Promise` (no confirmation data)\n- Throws on network/validation errors (wrap in try/catch)\n- Use `ctx.waitUntil()` for fire-and-forget pattern\n\n## Writing Events\n\n### Single Event\n\n```typescript\nawait env.STREAM.send([{\n user_id: \"12345\",\n event_type: \"purchase\",\n product_id: \"widget-001\",\n amount: 29.99\n}]);\n```\n\n### Batch Events\n\n```typescript\nconst events = [\n { user_id: \"user1\", event_type: \"view\" },\n { user_id: \"user2\", event_type: \"purchase\", amount: 50 }\n];\nawait env.STREAM.send(events);\n```\n\n**Limits:**\n- Max 1 MB per request\n- 5 MB/s per stream\n\n### Fire-and-Forget Pattern\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const event = { /* ... */ };\n \n // Don't block response on send\n ctx.waitUntil(env.STREAM.send([event]));\n \n return new Response('OK');\n }\n};\n```\n\n### Error Handling\n\n```typescript\ntry {\n await env.STREAM.send([event]);\n} catch (error) {\n console.error('Pipeline send failed:', error);\n // Log to another system, retry, or return error response\n return new Response('Failed to track event', { status: 500 });\n}\n```\n\n## HTTP Ingest API\n\n### Endpoint Format\n\n```\nhttps://{stream-id}.ingest.cloudflare.com\n```\n\nGet `{stream-id}` from: `npx wrangler pipelines streams list`\n\n### Request Format\n\n**CRITICAL:** Must send array, not single object\n\n```bash\n# ✅ Correct\ncurl -X POST https://{stream-id}.ingest.cloudflare.com \\\n -H \"Content-Type: application/json\" \\\n -d '[{\"user_id\": \"123\", \"event_type\": \"purchase\"}]'\n\n# ❌ Wrong - will fail\ncurl -X POST https://{stream-id}.ingest.cloudflare.com \\\n -H \"Content-Type: application/json\" \\\n -d '{\"user_id\": \"123\", \"event_type\": \"purchase\"}'\n```\n\n### Authentication\n\n```bash\ncurl -X POST https://{stream-id}.ingest.cloudflare.com \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -d '[{\"event\": \"data\"}]'\n```\n\n**Required permission:** Workers Pipeline Send\n\nCreate token: Dashboard → Workers → API tokens → Create with Pipeline Send permission\n\n### Response Codes\n\n| Code | Meaning | Action |\n|------|---------|--------|\n| 200 | Accepted | Success |\n| 400 | Invalid format | Check JSON array, schema match |\n| 401 | Auth failed | Verify token valid |\n| 413 | Payload too large | Split into smaller batches (<1 MB) |\n| 429 | Rate limited | Back off, retry with delay |\n| 5xx | Server error | Retry with exponential backoff |\n\n## SQL Functions Quick Reference\n\nAvailable in `INSERT INTO sink SELECT ... FROM stream` transformations:\n\n| Function | Example | Use Case |\n|----------|---------|----------|\n| `UPPER(s)` | `UPPER(event_type)` | Normalize strings |\n| `LOWER(s)` | `LOWER(email)` | Case-insensitive matching |\n| `CONCAT(...)` | `CONCAT(user_id, '_', product_id)` | Generate composite keys |\n| `CASE WHEN ... THEN ... END` | `CASE WHEN amount > 100 THEN 'high' ELSE 'low' END` | Conditional enrichment |\n| `CAST(x AS type)` | `CAST(timestamp AS string)` | Type conversion |\n| `COALESCE(x, y)` | `COALESCE(amount, 0.0)` | Default values |\n| Math operators | `amount * 1.1`, `price / quantity` | Calculations |\n| Comparison | `amount > 100`, `status IN ('active', 'pending')` | Filtering |\n\n**String types for CAST:** `string`, `int32`, `int64`, `float32`, `float64`, `bool`, `timestamp`\n\nFull reference: [Pipelines SQL Reference](https://developers.cloudflare.com/pipelines/sql-reference/)\n\n## SQL Transform Examples\n\n### Filter Events\n\n```sql\nINSERT INTO my_sink\nSELECT * FROM my_stream\nWHERE event_type = 'purchase' AND amount > 100\n```\n\n### Select Specific Fields\n\n```sql\nINSERT INTO my_sink\nSELECT user_id, event_type, timestamp, amount\nFROM my_stream\n```\n\n### Transform and Enrich\n\n```sql\nINSERT INTO my_sink\nSELECT\n user_id,\n UPPER(event_type) as event_type,\n timestamp,\n amount * 1.1 as amount_with_tax,\n CONCAT(user_id, '_', product_id) as unique_key,\n CASE\n WHEN amount > 1000 THEN 'high_value'\n WHEN amount > 100 THEN 'medium_value'\n ELSE 'low_value'\n END as customer_tier\nFROM my_stream\nWHERE event_type IN ('purchase', 'refund')\n```\n\n## Querying Results (R2 Data Catalog)\n\n```bash\nexport WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_CATALOG_TOKEN\n\nnpx wrangler r2 sql query \"warehouse_name\" \"\nSELECT \n event_type,\n COUNT(*) as event_count,\n SUM(amount) as total_revenue\nFROM default.my_table\nWHERE event_type = 'purchase'\n AND timestamp >= '2025-01-01'\nGROUP BY event_type\nORDER BY total_revenue DESC\nLIMIT 100\"\n```\n\n**Note:** Iceberg tables support standard SQL queries with GROUP BY, JOINs, WHERE, ORDER BY, etc.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pipelines/configuration.md", "content": "# Pipelines Configuration\n\n## Worker Binding\n\n```jsonc\n// wrangler.jsonc\n{\n \"pipelines\": [\n { \"pipeline\": \"\", \"binding\": \"STREAM\" }\n ]\n}\n```\n\nGet stream ID: `npx wrangler pipelines streams list`\n\n## Schema (Structured Streams)\n\n```json\n{\n \"fields\": [\n { \"name\": \"user_id\", \"type\": \"string\", \"required\": true },\n { \"name\": \"event_type\", \"type\": \"string\", \"required\": true },\n { \"name\": \"amount\", \"type\": \"float64\", \"required\": false },\n { \"name\": \"timestamp\", \"type\": \"timestamp\", \"required\": true }\n ]\n}\n```\n\n**Types:** `string`, `int32`, `int64`, `float32`, `float64`, `bool`, `timestamp`, `json`, `binary`, `list`, `struct`\n\n## Stream Setup\n\n```bash\n# With schema\nnpx wrangler pipelines streams create my-stream --schema-file schema.json\n\n# Unstructured (no validation)\nnpx wrangler pipelines streams create my-stream\n\n# List/get/delete\nnpx wrangler pipelines streams list\nnpx wrangler pipelines streams get \nnpx wrangler pipelines streams delete \n```\n\n## Sink Configuration\n\n**R2 Data Catalog (Iceberg):**\n```bash\nnpx wrangler pipelines sinks create my-sink \\\n --type r2-data-catalog \\\n --bucket my-bucket --namespace default --table events \\\n --catalog-token $TOKEN \\\n --compression zstd --roll-interval 60\n```\n\n**R2 Raw (Parquet):**\n```bash\nnpx wrangler pipelines sinks create my-sink \\\n --type r2 --bucket my-bucket --format parquet \\\n --path analytics/events \\\n --partitioning \"year=%Y/month=%m/day=%d\" \\\n --access-key-id $KEY --secret-access-key $SECRET\n```\n\n| Option | Values | Guidance |\n|--------|--------|----------|\n| `--compression` | `zstd`, `snappy`, `gzip` | `zstd` best ratio, `snappy` fastest |\n| `--roll-interval` | Seconds | Low latency: 10-60, Query perf: 300 |\n| `--roll-size` | MB | Larger = better compression |\n\n## Pipeline Creation\n\n```bash\nnpx wrangler pipelines create my-pipeline \\\n --sql \"INSERT INTO my_sink SELECT * FROM my_stream WHERE event_type = 'purchase'\"\n```\n\n**⚠️ Pipelines are immutable** - cannot modify SQL. Must delete/recreate.\n\n## Credentials\n\n| Type | Permission | Get From |\n|------|------------|----------|\n| Catalog token | R2 Admin Read & Write | Dashboard → R2 → API tokens |\n| R2 credentials | Object Read & Write | `wrangler r2 bucket create` output |\n| HTTP ingest token | Workers Pipeline Send | Dashboard → Workers → API tokens |\n\n## Complete Example\n\n```bash\nnpx wrangler r2 bucket create my-bucket\nnpx wrangler r2 bucket catalog enable my-bucket\nnpx wrangler pipelines streams create my-stream --schema-file schema.json\nnpx wrangler pipelines sinks create my-sink --type r2-data-catalog --bucket my-bucket ...\nnpx wrangler pipelines create my-pipeline --sql \"INSERT INTO my_sink SELECT * FROM my_stream\"\nnpx wrangler deploy\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pipelines/gotchas.md", "content": "# Pipelines Gotchas\n\n## Critical Issues\n\n### Events Silently Dropped\n\n**Most common issue.** Events accepted (HTTP 200) but never appear in sink.\n\n**Causes:**\n1. Schema validation fails - structured streams drop invalid events silently\n2. Waiting for roll interval (10-300s) - expected behavior\n\n**Solution:** Validate client-side with Zod:\n```typescript\nconst EventSchema = z.object({ user_id: z.string(), amount: z.number() });\ntry {\n const validated = EventSchema.parse(rawEvent);\n await env.STREAM.send([validated]);\n} catch (e) { /* get immediate feedback */ }\n```\n\n### Pipelines Are Immutable\n\nCannot modify SQL after creation. Must delete and recreate.\n\n```bash\nnpx wrangler pipelines delete old-pipeline\nnpx wrangler pipelines create new-pipeline --sql \"...\"\n```\n\n**Tip:** Use version naming (`events-pipeline-v1`) and keep SQL in version control.\n\n### Worker Binding Not Found\n\n**`env.STREAM is undefined`**\n\n1. Use **stream ID** (not pipeline ID) in `wrangler.jsonc`\n2. Redeploy after adding binding\n\n```bash\nnpx wrangler pipelines streams list # Get stream ID\nnpx wrangler deploy\n```\n\n## Common Errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| Events not in R2 | Roll interval not elapsed | Wait 10-300s, check `roll_interval` |\n| Schema validation failures | Type mismatch, missing fields | Validate client-side |\n| Rate limit (429) | >5 MB/s per stream | Batch events, request increase |\n| Payload too large (413) | >1 MB request | Split into smaller batches |\n| Cannot delete stream | Pipeline references it | Delete pipelines first |\n| Sink credential errors | Token expired | Recreate sink with new credentials |\n\n## Limits (Open Beta)\n\n| Resource | Limit |\n|----------|-------|\n| Streams/Sinks/Pipelines per account | 20 each |\n| Payload size | 1 MB |\n| Ingest rate per stream | 5 MB/s |\n| Event retention | 24 hours |\n| Recommended batch size | 100 events |\n\n## SQL Limitations\n\n- **No JOINs** - single stream per pipeline\n- **No window functions** - basic SQL only\n- **No subqueries** - must use `INSERT INTO ... SELECT ... FROM`\n- **No schema evolution** - cannot modify after creation\n\n## Debug Checklist\n\n- [ ] Stream exists: `npx wrangler pipelines streams list`\n- [ ] Pipeline healthy: `npx wrangler pipelines get `\n- [ ] SQL syntax matches schema\n- [ ] Worker redeployed after binding added\n- [ ] Waited for roll interval\n- [ ] Accepted vs processed count matches (no validation drops)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pipelines/patterns.md", "content": "# Pipelines Patterns\n\n## Fire-and-Forget\n\n```typescript\nexport default {\n async fetch(request, env, ctx) {\n const event = { user_id: '...', event_type: 'page_view', timestamp: new Date().toISOString() };\n ctx.waitUntil(env.STREAM.send([event])); // Don't block response\n return new Response('OK');\n }\n};\n```\n\n## Schema Validation with Zod\n\n```typescript\nimport { z } from 'zod';\n\nconst EventSchema = z.object({\n user_id: z.string(),\n event_type: z.enum(['purchase', 'view']),\n amount: z.number().positive().optional()\n});\n\nconst validated = EventSchema.parse(rawEvent); // Throws on invalid\nawait env.STREAM.send([validated]);\n```\n\n**Why:** Structured streams drop invalid events silently. Client validation gives immediate feedback.\n\n## SQL Transform Patterns\n\n```sql\n-- Filter early (reduce storage)\nINSERT INTO my_sink\nSELECT user_id, event_type, amount\nFROM my_stream\nWHERE event_type = 'purchase' AND amount > 10\n\n-- Select only needed fields\nINSERT INTO my_sink\nSELECT user_id, event_type, timestamp FROM my_stream\n\n-- Enrich with CASE\nINSERT INTO my_sink\nSELECT user_id, amount,\n CASE WHEN amount > 1000 THEN 'vip' ELSE 'standard' END as tier\nFROM my_stream\n```\n\n## Pipelines + Queues Fan-out\n\n```typescript\nawait Promise.all([\n env.ANALYTICS_STREAM.send([event]), // Long-term storage\n env.PROCESS_QUEUE.send(event) // Immediate processing\n]);\n```\n\n| Need | Use |\n|------|-----|\n| Long-term storage, SQL queries | Pipelines |\n| Immediate processing, retries | Queues |\n| Both | Fan-out pattern |\n\n## Performance Tuning\n\n| Goal | Config |\n|------|--------|\n| Low latency | `--roll-interval 10` |\n| Query performance | `--roll-interval 300 --roll-size 100` |\n| Cost optimal | `--compression zstd --roll-interval 300` |\n\n## Schema Evolution\n\nPipelines are immutable. Use versioning:\n\n```bash\n# Create v2 stream/sink/pipeline\nnpx wrangler pipelines streams create events-v2 --schema-file v2.json\n\n# Dual-write during transition\nawait Promise.all([env.EVENTS_V1.send([event]), env.EVENTS_V2.send([event])]);\n\n# Query across versions with UNION ALL\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pulumi/README.md", "content": "# Cloudflare Pulumi Provider\n\nExpert guidance for Cloudflare Pulumi Provider (@pulumi/cloudflare).\n\n## Overview\n\nProgrammatic management of Cloudflare resources: Workers, Pages, D1, KV, R2, DNS, Queues, etc.\n\n**Packages:**\n- TypeScript/JS: `@pulumi/cloudflare`\n- Python: `pulumi-cloudflare`\n- Go: `github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare`\n- .NET: `Pulumi.Cloudflare`\n\n**Version:** v6.x\n\n## Core Principles\n\n1. Use API tokens (not legacy API keys)\n2. Store accountId in stack config\n3. Match binding names across code/config\n4. Use `module: true` for ES modules\n5. Set `compatibilityDate` to lock behavior\n\n## Authentication\n\n```typescript\nimport * as cloudflare from \"@pulumi/cloudflare\";\n\n// API Token (recommended): CLOUDFLARE_API_TOKEN env\nconst provider = new cloudflare.Provider(\"cf\", { apiToken: process.env.CLOUDFLARE_API_TOKEN });\n\n// API Key (legacy): CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL env\nconst provider = new cloudflare.Provider(\"cf\", { apiKey: process.env.CLOUDFLARE_API_KEY, email: process.env.CLOUDFLARE_EMAIL });\n\n// API User Service Key: CLOUDFLARE_API_USER_SERVICE_KEY env\nconst provider = new cloudflare.Provider(\"cf\", { apiUserServiceKey: process.env.CLOUDFLARE_API_USER_SERVICE_KEY });\n```\n\n## Setup\n\n**Pulumi.yaml:**\n```yaml\nname: my-cloudflare-app\nruntime: nodejs\nconfig:\n cloudflare:apiToken:\n value: ${CLOUDFLARE_API_TOKEN}\n```\n\n**Pulumi..yaml:**\n```yaml\nconfig:\n cloudflare:accountId: \"abc123...\"\n```\n\n**index.ts:**\n```typescript\nimport * as pulumi from \"@pulumi/pulumi\";\nimport * as cloudflare from \"@pulumi/cloudflare\";\nconst accountId = new pulumi.Config(\"cloudflare\").require(\"accountId\");\n```\n\n## Common Resource Types\n- `Provider` - Provider config\n- `WorkerScript` - Worker\n- `WorkersKvNamespace` - KV\n- `R2Bucket` - R2\n- `D1Database` - D1\n- `Queue` - Queue\n- `PagesProject` - Pages\n- `DnsRecord` - DNS\n- `WorkerRoute` - Worker route\n- `WorkersDomain` - Custom domain\n\n## Key Properties\n- `accountId` - Required for most resources\n- `zoneId` - Required for DNS/domain\n- `name`/`title` - Resource identifier\n- `*Bindings` - Connect resources to Workers\n\n## Reading Order\n\n| Order | File | What | When to Read |\n|-------|------|------|--------------|\n| 1 | [configuration.md](./configuration.md) | Resource config for Workers/KV/D1/R2/Queues/Pages | First time setup, resource reference |\n| 2 | [patterns.md](./patterns.md) | Architecture patterns, multi-env, component resources | Building complex apps, best practices |\n| 3 | [api.md](./api.md) | Outputs, dependencies, imports, dynamic providers | Advanced features, integrations |\n| 4 | [gotchas.md](./gotchas.md) | Common errors, troubleshooting, limits | Debugging, deployment issues |\n\n## In This Reference\n- [configuration.md](./configuration.md) - Provider config, stack setup, Workers/bindings\n- [api.md](./api.md) - Resource types, Workers script, KV/D1/R2/queues/Pages\n- [patterns.md](./patterns.md) - Multi-env, secrets, CI/CD, stack management\n- [gotchas.md](./gotchas.md) - State issues, deployment failures, limits\n\n## See Also\n- [terraform](../terraform/) - Alternative IaC for Cloudflare\n- [wrangler](../wrangler/) - CLI deployment alternative\n- [workers](../workers/) - Worker runtime documentation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pulumi/api.md", "content": "# API & Data Sources\n\n## Outputs and Exports\n\nExport resource identifiers:\n\n```typescript\nexport const kvId = kv.id;\nexport const bucketName = bucket.name;\nexport const workerUrl = worker.subdomain;\nexport const dbId = db.id;\n```\n\n## Resource Dependencies\n\nImplicit dependencies via outputs:\n\n```typescript\nconst kv = new cloudflare.WorkersKvNamespace(\"kv\", {\n accountId: accountId,\n title: \"my-kv\",\n});\n\n// Worker depends on KV (implicit via kv.id)\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n accountId: accountId,\n name: \"my-worker\",\n content: code,\n kvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}], // Creates dependency\n});\n```\n\nExplicit dependencies:\n\n```typescript\nconst migration = new command.local.Command(\"migration\", {\n create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,\n}, {dependsOn: [db]});\n\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n accountId: accountId,\n name: \"worker\",\n content: code,\n d1DatabaseBindings: [{name: \"DB\", databaseId: db.id}],\n}, {dependsOn: [migration]}); // Ensure migrations run first\n```\n\n## Using Outputs with API Calls\n\n```typescript\nconst db = new cloudflare.D1Database(\"db\", {accountId, name: \"my-db\"});\n\ndb.id.apply(async (dbId) => {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${dbId}/query`,\n {method: \"POST\", headers: {\"Authorization\": `Bearer ${apiToken}`, \"Content-Type\": \"application/json\"},\n body: JSON.stringify({sql: \"CREATE TABLE users (id INT)\"})}\n );\n return response.json();\n});\n```\n\n## Custom Dynamic Providers\n\nFor resources not in provider:\n\n```typescript\nimport * as pulumi from \"@pulumi/pulumi\";\n\nclass D1MigrationProvider implements pulumi.dynamic.ResourceProvider {\n async create(inputs: any): Promise {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${inputs.accountId}/d1/database/${inputs.databaseId}/query`,\n {method: \"POST\", headers: {\"Authorization\": `Bearer ${inputs.apiToken}`, \"Content-Type\": \"application/json\"},\n body: JSON.stringify({sql: inputs.sql})}\n );\n return {id: `${inputs.databaseId}-${Date.now()}`, outs: await response.json()};\n }\n async update(id: string, olds: any, news: any): Promise {\n if (olds.sql !== news.sql) await this.create(news);\n return {};\n }\n async delete(id: string, props: any): Promise {}\n}\n\nclass D1Migration extends pulumi.dynamic.Resource {\n constructor(name: string, args: any, opts?: pulumi.CustomResourceOptions) {\n super(new D1MigrationProvider(), name, args, opts);\n }\n}\n\nconst migration = new D1Migration(\"migration\", {\n accountId, databaseId: db.id, apiToken, sql: \"CREATE TABLE users (id INT)\",\n}, {dependsOn: [db]});\n```\n\n## Data Sources\n\n**Get Zone:**\n```typescript\nconst zone = cloudflare.getZone({name: \"example.com\"});\nconst zoneId = zone.then(z => z.id);\n```\n\n**Get Accounts (via API):**\nUse Cloudflare API directly or custom dynamic resources.\n\n## Import Existing Resources\n\n```bash\n# Import worker\npulumi import cloudflare:index/workerScript:WorkerScript my-worker /\n\n# Import KV namespace\npulumi import cloudflare:index/workersKvNamespace:WorkersKvNamespace my-kv \n\n# Import R2 bucket\npulumi import cloudflare:index/r2Bucket:R2Bucket my-bucket /\n\n# Import D1 database\npulumi import cloudflare:index/d1Database:D1Database my-db /\n\n# Import DNS record\npulumi import cloudflare:index/dnsRecord:DnsRecord my-record /\n```\n\n## Secrets Management\n\n```typescript\nimport * as pulumi from \"@pulumi/pulumi\";\n\nconst config = new pulumi.Config();\nconst apiKey = config.requireSecret(\"apiKey\"); // Encrypted in state\n\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n accountId: accountId,\n name: \"my-worker\",\n content: code,\n secretTextBindings: [{name: \"API_KEY\", text: apiKey}],\n});\n```\n\nStore secrets:\n```bash\npulumi config set --secret apiKey \"secret-value\"\n```\n\n## Transform Pattern\n\nModify resource args before creation:\n\n```typescript\nimport {Transform} from \"@pulumi/pulumi\";\n\ninterface BucketArgs {\n accountId: pulumi.Input;\n transform?: {bucket?: Transform};\n}\n\nfunction createBucket(name: string, args: BucketArgs) {\n const bucketArgs: cloudflare.R2BucketArgs = {\n accountId: args.accountId,\n name: name,\n location: \"auto\",\n };\n const finalArgs = args.transform?.bucket?.(bucketArgs) ?? bucketArgs;\n return new cloudflare.R2Bucket(name, finalArgs);\n}\n```\n\n## v6.x Worker Versioning Resources\n\n**Worker** - Container for versions:\n```typescript\nconst worker = new cloudflare.Worker(\"api\", {accountId, name: \"api-worker\"});\nexport const workerId = worker.id;\n```\n\n**WorkerVersion** - Immutable code + config:\n```typescript\nconst version = new cloudflare.WorkerVersion(\"v1\", {\n accountId, workerId: worker.id,\n content: fs.readFileSync(\"./dist/worker.js\", \"utf8\"),\n compatibilityDate: \"2025-01-01\",\n});\nexport const versionId = version.id;\n```\n\n**WorkersDeployment** - Active deployment with bindings:\n```typescript\nconst deployment = new cloudflare.WorkersDeployment(\"prod\", {\n accountId, workerId: worker.id, versionId: version.id,\n kvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}],\n});\n```\n\n**Use:** Advanced deployments (canary, blue-green). Most apps should use `WorkerScript` (auto-versioning).\n\n---\nSee: [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pulumi/configuration.md", "content": "# Resource Configuration\n\n## Workers (cloudflare.WorkerScript)\n\n```typescript\nimport * as cloudflare from \"@pulumi/cloudflare\";\nimport * as fs from \"fs\";\n\nconst worker = new cloudflare.WorkerScript(\"my-worker\", {\n accountId: accountId,\n name: \"my-worker\",\n content: fs.readFileSync(\"./dist/worker.js\", \"utf8\"),\n module: true, // ES modules\n compatibilityDate: \"2025-01-01\",\n compatibilityFlags: [\"nodejs_compat\"],\n \n // v6.x: Observability\n logpush: true, // Enable Workers Logpush\n tailConsumers: [{service: \"log-consumer\"}], // Stream logs to Worker\n \n // v6.x: Placement\n placement: {mode: \"smart\"}, // Smart placement for latency optimization\n \n // Bindings\n kvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}],\n r2BucketBindings: [{name: \"MY_BUCKET\", bucketName: bucket.name}],\n d1DatabaseBindings: [{name: \"DB\", databaseId: db.id}],\n queueBindings: [{name: \"MY_QUEUE\", queue: queue.id}],\n serviceBindings: [{name: \"OTHER_SERVICE\", service: other.name}],\n plainTextBindings: [{name: \"ENV_VAR\", text: \"value\"}],\n secretTextBindings: [{name: \"API_KEY\", text: secret}],\n \n // v6.x: Advanced bindings\n analyticsEngineBindings: [{name: \"ANALYTICS\", dataset: \"my-dataset\"}],\n browserBinding: {name: \"BROWSER\"}, // Browser Rendering\n aiBinding: {name: \"AI\"}, // Workers AI\n hyperdriveBindings: [{name: \"HYPERDRIVE\", id: hyperdriveConfig.id}],\n});\n```\n\n## Workers KV (cloudflare.WorkersKvNamespace)\n\n```typescript\nconst kv = new cloudflare.WorkersKvNamespace(\"my-kv\", {\n accountId: accountId,\n title: \"my-kv-namespace\",\n});\n\n// Write values\nconst kvValue = new cloudflare.WorkersKvValue(\"config\", {\n accountId: accountId,\n namespaceId: kv.id,\n key: \"config\",\n value: JSON.stringify({foo: \"bar\"}),\n});\n```\n\n## R2 Buckets (cloudflare.R2Bucket)\n\n```typescript\nconst bucket = new cloudflare.R2Bucket(\"my-bucket\", {\n accountId: accountId,\n name: \"my-bucket\",\n location: \"auto\", // or \"wnam\", etc.\n});\n```\n\n## D1 Databases (cloudflare.D1Database)\n\n```typescript\nconst db = new cloudflare.D1Database(\"my-db\", {accountId, name: \"my-database\"});\n\n// Migrations via wrangler\nimport * as command from \"@pulumi/command\";\nconst migration = new command.local.Command(\"d1-migration\", {\n create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,\n}, {dependsOn: [db]});\n```\n\n## Queues (cloudflare.Queue)\n\n```typescript\nconst queue = new cloudflare.Queue(\"my-queue\", {accountId, name: \"my-queue\"});\n\n// Producer\nconst producer = new cloudflare.WorkerScript(\"producer\", {\n accountId, name: \"producer\", content: code,\n queueBindings: [{name: \"MY_QUEUE\", queue: queue.id}],\n});\n\n// Consumer\nconst consumer = new cloudflare.WorkerScript(\"consumer\", {\n accountId, name: \"consumer\", content: code,\n queueConsumers: [{queue: queue.name, maxBatchSize: 10, maxRetries: 3}],\n});\n```\n\n## Pages Projects (cloudflare.PagesProject)\n\n```typescript\nconst pages = new cloudflare.PagesProject(\"my-site\", {\n accountId, name: \"my-site\", productionBranch: \"main\",\n buildConfig: {buildCommand: \"npm run build\", destinationDir: \"dist\"},\n source: {\n type: \"github\",\n config: {owner: \"my-org\", repoName: \"my-repo\", productionBranch: \"main\"},\n },\n deploymentConfigs: {\n production: {\n environmentVariables: {NODE_VERSION: \"18\"},\n kvNamespaces: {MY_KV: kv.id},\n d1Databases: {DB: db.id},\n },\n },\n});\n```\n\n## DNS Records (cloudflare.DnsRecord)\n\n```typescript\nconst zone = cloudflare.getZone({name: \"example.com\"});\nconst record = new cloudflare.DnsRecord(\"www\", {\n zoneId: zone.then(z => z.id), name: \"www\", type: \"A\",\n content: \"192.0.2.1\", ttl: 3600, proxied: true,\n});\n```\n\n## Workers Domains/Routes\n\n```typescript\n// Route (pattern-based)\nconst route = new cloudflare.WorkerRoute(\"my-route\", {\n zoneId: zoneId,\n pattern: \"example.com/api/*\",\n scriptName: worker.name,\n});\n\n// Domain (dedicated subdomain)\nconst domain = new cloudflare.WorkersDomain(\"my-domain\", {\n accountId: accountId,\n hostname: \"api.example.com\",\n service: worker.name,\n zoneId: zoneId,\n});\n```\n\n## Assets Configuration (v6.x)\n\nServe static assets from Workers:\n\n```typescript\nconst worker = new cloudflare.WorkerScript(\"app\", {\n accountId: accountId,\n name: \"my-app\",\n content: code,\n assets: {\n path: \"./public\", // Local directory\n // Assets uploaded and served from Workers\n },\n});\n```\n\n## v6.x Versioned Deployments (Advanced)\n\nFor gradual rollouts, use 3-resource pattern:\n\n```typescript\n// 1. Worker (container for versions)\nconst worker = new cloudflare.Worker(\"api\", {\n accountId: accountId,\n name: \"api-worker\",\n});\n\n// 2. Version (immutable code + config)\nconst version = new cloudflare.WorkerVersion(\"v1\", {\n accountId: accountId,\n workerId: worker.id,\n content: fs.readFileSync(\"./dist/worker.js\", \"utf8\"),\n compatibilityDate: \"2025-01-01\",\n compatibilityFlags: [\"nodejs_compat\"],\n // Note: Bindings configured at deployment level\n});\n\n// 3. Deployment (version + bindings + traffic split)\nconst deployment = new cloudflare.WorkersDeployment(\"prod\", {\n accountId: accountId,\n workerId: worker.id,\n versionId: version.id,\n // Bindings applied to deployment\n kvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}],\n});\n```\n\n**When to use:** Blue-green deployments, canary releases, gradual rollouts \n**When NOT to use:** Simple single-version deployments (use WorkerScript)\n\n---\nSee: [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pulumi/gotchas.md", "content": "# Troubleshooting & Best Practices\n\n## Common Errors\n\n### \"No bundler/build step\" - Pulumi uploads raw code\n\n**Problem:** Worker fails with \"Cannot use import statement outside a module\" \n**Cause:** Pulumi doesn't bundle Worker code - uploads exactly what you provide \n**Solution:** Build Worker BEFORE Pulumi deploy\n\n```typescript\n// WRONG: Pulumi won't bundle this\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n content: fs.readFileSync(\"./src/index.ts\", \"utf8\"), // Raw TS file\n});\n\n// RIGHT: Build first, then deploy\nimport * as command from \"@pulumi/command\";\nconst build = new command.local.Command(\"build\", {\n create: \"npm run build\",\n dir: \"./worker\",\n});\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n content: build.stdout.apply(() => fs.readFileSync(\"./worker/dist/index.js\", \"utf8\")),\n}, {dependsOn: [build]});\n```\n\n### \"wrangler.toml not consumed\" - Config drift\n\n**Problem:** Local wrangler dev works, Pulumi deploy fails \n**Cause:** Pulumi ignores wrangler.toml - must duplicate config \n**Solution:** Generate wrangler.toml from Pulumi or keep synced manually\n\n```typescript\n// Pattern: Export Pulumi config to wrangler.toml\nconst workerConfig = {\n name: \"my-worker\",\n compatibilityDate: \"2025-01-01\",\n compatibilityFlags: [\"nodejs_compat\"],\n};\n\nnew command.local.Command(\"generate-wrangler\", {\n create: pulumi.interpolate`cat > wrangler.toml <.yaml\nconfig:\n cloudflare:accountId: \"abc123...\"\n```\n\n### \"Binding name mismatch\"\n\n**Problem:** Worker fails with \"env.MY_KV is undefined\" \n**Cause:** Binding name in Pulumi != name in Worker code \n**Solution:** Match exactly (case-sensitive)\n\n```typescript\n// Pulumi\nkvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}]\n\n// Worker code\nexport default { async fetch(request, env) { await env.MY_KV.get(\"key\"); }}\n```\n\n### \"API token permissions insufficient\"\n\n**Problem:** `Error: authentication error (10000)` \n**Cause:** Token lacks required permissions \n**Solution:** Grant token permissions: Account.Workers Scripts:Edit, Account.Account Settings:Read\n\n### \"Resource not found after import\"\n\n**Problem:** Imported resource shows as changed on next `pulumi up` \n**Cause:** State mismatch between actual resource and Pulumi config \n**Solution:** Check property names/types match exactly\n\n```bash\npulumi import cloudflare:index/workerScript:WorkerScript my-worker /\npulumi preview # If shows changes, adjust Pulumi code to match actual resource\n```\n\n### \"v6.x Worker versioning confusion\"\n\n**Problem:** Worker deployed but not receiving traffic \n**Cause:** v6.x requires Worker + WorkerVersion + WorkersDeployment (3 resources) \n**Solution:** Use WorkerScript (auto-versioning) OR full versioning pattern\n\n```typescript\n// SIMPLE: WorkerScript auto-versions (default behavior)\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n accountId, name: \"my-worker\", content: code,\n});\n\n// ADVANCED: Manual versioning for gradual rollouts (v6.x)\nconst worker = new cloudflare.Worker(\"worker\", {accountId, name: \"my-worker\"});\nconst version = new cloudflare.WorkerVersion(\"v1\", {\n accountId, workerId: worker.id, content: code, compatibilityDate: \"2025-01-01\",\n});\nconst deployment = new cloudflare.WorkersDeployment(\"prod\", {\n accountId, workerId: worker.id, versionId: version.id,\n});\n```\n\n## Best Practices\n\n1. **Always set compatibilityDate** - Locks Worker behavior, prevents breaking changes\n2. **Build before deploy** - Pulumi doesn't bundle; use Command resource or CI build step\n3. **Match binding names** - Case-sensitive, must match between Pulumi and Worker code\n4. **Use dependsOn for migrations** - Ensure D1 migrations run before Worker deploys\n5. **Version Worker content** - Add VERSION binding to force redeployment on content changes\n6. **Store secrets in stack config** - Use `pulumi config set --secret` for API keys\n\n## Limits\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| Worker script size | 10 MB | Includes all dependencies, after compression |\n| Worker CPU time | 50ms (free), 30s (paid) | Per request |\n| KV keys per namespace | Unlimited | 1000 ops/sec write, 100k ops/sec read |\n| R2 storage | Unlimited | Class A ops: 1M/mo free, Class B: 10M/mo free |\n| D1 databases | 50,000 per account | Free: 10 per account, 5 GB each |\n| Queues | 10,000 per account | Free: 1M ops/day |\n| Pages projects | 500 per account | Free: 100 projects |\n| API requests | Varies by plan | ~1200 req/5min on free |\n\n## Resources\n\n- **Pulumi Registry:** https://www.pulumi.com/registry/packages/cloudflare/\n- **API Docs:** https://www.pulumi.com/registry/packages/cloudflare/api-docs/\n- **GitHub:** https://github.com/pulumi/pulumi-cloudflare\n- **Cloudflare Docs:** https://developers.cloudflare.com/\n- **Workers Docs:** https://developers.cloudflare.com/workers/\n\n---\nSee: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/pulumi/patterns.md", "content": "# Architecture Patterns\n\n## Component Resources\n\n```typescript\nclass WorkerApp extends pulumi.ComponentResource {\n constructor(name: string, args: WorkerAppArgs, opts?) {\n super(\"custom:cloudflare:WorkerApp\", name, {}, opts);\n const defaultOpts = {parent: this};\n\n this.kv = new cloudflare.WorkersKvNamespace(`${name}-kv`, {accountId: args.accountId, title: `${name}-kv`}, defaultOpts);\n this.worker = new cloudflare.WorkerScript(`${name}-worker`, {\n accountId: args.accountId, name: `${name}-worker`, content: args.workerCode,\n module: true, kvNamespaceBindings: [{name: \"KV\", namespaceId: this.kv.id}],\n }, defaultOpts);\n this.domain = new cloudflare.WorkersDomain(`${name}-domain`, {\n accountId: args.accountId, hostname: args.domain, service: this.worker.name,\n }, defaultOpts);\n }\n}\n```\n\n## Full-Stack Worker App\n\n```typescript\nconst kv = new cloudflare.WorkersKvNamespace(\"cache\", {accountId, title: \"api-cache\"});\nconst db = new cloudflare.D1Database(\"db\", {accountId, name: \"app-database\"});\nconst bucket = new cloudflare.R2Bucket(\"assets\", {accountId, name: \"app-assets\"});\n\nconst apiWorker = new cloudflare.WorkerScript(\"api\", {\n accountId, name: \"api-worker\", content: fs.readFileSync(\"./dist/api.js\", \"utf8\"),\n module: true, kvNamespaceBindings: [{name: \"CACHE\", namespaceId: kv.id}],\n d1DatabaseBindings: [{name: \"DB\", databaseId: db.id}],\n r2BucketBindings: [{name: \"ASSETS\", bucketName: bucket.name}],\n});\n```\n\n## Multi-Environment Setup\n\n```typescript\nconst stack = pulumi.getStack();\nconst worker = new cloudflare.WorkerScript(`worker-${stack}`, {\n accountId, name: `my-worker-${stack}`, content: code,\n plainTextBindings: [{name: \"ENVIRONMENT\", text: stack}],\n});\n```\n\n## Queue-Based Processing\n\n```typescript\nconst queue = new cloudflare.Queue(\"processing-queue\", {accountId, name: \"image-processing\"});\n\n// Producer: API receives requests\nconst apiWorker = new cloudflare.WorkerScript(\"api\", {\n accountId, name: \"api-worker\", content: apiCode,\n queueBindings: [{name: \"PROCESSING_QUEUE\", queue: queue.id}],\n});\n\n// Consumer: Process async\nconst processorWorker = new cloudflare.WorkerScript(\"processor\", {\n accountId, name: \"processor-worker\", content: processorCode,\n queueConsumers: [{queue: queue.name, maxBatchSize: 10, maxRetries: 3, maxWaitTimeMs: 5000}],\n r2BucketBindings: [{name: \"OUTPUT_BUCKET\", bucketName: outputBucket.name}],\n});\n```\n\n## Microservices with Service Bindings\n\n```typescript\nconst authWorker = new cloudflare.WorkerScript(\"auth\", {accountId, name: \"auth-service\", content: authCode});\nconst apiWorker = new cloudflare.WorkerScript(\"api\", {\n accountId, name: \"api-service\", content: apiCode,\n serviceBindings: [{name: \"AUTH\", service: authWorker.name}],\n});\n```\n\n## Event-Driven Architecture\n\n```typescript\nconst eventQueue = new cloudflare.Queue(\"events\", {accountId, name: \"event-bus\"});\nconst producer = new cloudflare.WorkerScript(\"producer\", {\n accountId, name: \"api-producer\", content: producerCode,\n queueBindings: [{name: \"EVENTS\", queue: eventQueue.id}],\n});\nconst consumer = new cloudflare.WorkerScript(\"consumer\", {\n accountId, name: \"email-consumer\", content: consumerCode,\n queueConsumers: [{queue: eventQueue.name, maxBatchSize: 10}],\n});\n```\n\n## v6.x Versioned Deployments (Blue-Green/Canary)\n\n```typescript\nconst worker = new cloudflare.Worker(\"api\", {accountId, name: \"api-worker\"});\nconst v1 = new cloudflare.WorkerVersion(\"v1\", {accountId, workerId: worker.id, content: fs.readFileSync(\"./dist/v1.js\", \"utf8\"), compatibilityDate: \"2025-01-01\"});\nconst v2 = new cloudflare.WorkerVersion(\"v2\", {accountId, workerId: worker.id, content: fs.readFileSync(\"./dist/v2.js\", \"utf8\"), compatibilityDate: \"2025-01-01\"});\n\n// Gradual rollout: 10% v2, 90% v1\nconst deployment = new cloudflare.WorkersDeployment(\"canary\", {\n accountId, workerId: worker.id,\n versions: [{versionId: v2.id, percentage: 10}, {versionId: v1.id, percentage: 90}],\n kvNamespaceBindings: [{name: \"MY_KV\", namespaceId: kv.id}],\n});\n```\n\n**Use:** Canary releases, A/B testing, blue-green. Most apps use `WorkerScript` (auto-versioning).\n\n## Wrangler.toml Generation (Bridge IaC with Local Dev)\n\nGenerate wrangler.toml from Pulumi config to keep local dev in sync:\n\n```typescript\nimport * as command from \"@pulumi/command\";\n\nconst workerConfig = {\n name: \"my-worker\",\n compatibilityDate: \"2025-01-01\",\n compatibilityFlags: [\"nodejs_compat\"],\n};\n\n// Create resources\nconst kv = new cloudflare.WorkersKvNamespace(\"kv\", {accountId, title: \"my-kv\"});\nconst db = new cloudflare.D1Database(\"db\", {accountId, name: \"my-db\"});\nconst bucket = new cloudflare.R2Bucket(\"bucket\", {accountId, name: \"my-bucket\"});\n\n// Generate wrangler.toml after resources created\nconst wranglerGen = new command.local.Command(\"gen-wrangler\", {\n create: pulumi.interpolate`cat > wrangler.toml < fs.readFileSync(\"./worker/dist/index.js\", \"utf8\")),\n}, {dependsOn: [build]});\n```\n\n## Content SHA Pattern (Force Updates)\n\nPrevent false \"no changes\" detections:\n\n```typescript\nconst version = Date.now().toString();\nconst worker = new cloudflare.WorkerScript(\"worker\", {\n accountId, name: \"my-worker\", content: code,\n plainTextBindings: [{name: \"VERSION\", text: version}], // Forces deployment\n});\n```\n\n---\nSee: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/queues/README.md", "content": "# Cloudflare Queues\n\nFlexible message queuing for async task processing with guaranteed at-least-once delivery and configurable batching.\n\n## Overview\n\nQueues provide:\n- At-least-once delivery guarantee\n- Push-based (Worker) and pull-based (HTTP) consumers\n- Configurable batching and retries\n- Dead Letter Queues (DLQ)\n- Delays up to 12 hours\n\n**Use cases:** Async processing, API buffering, rate limiting, event workflows, deferred jobs\n\n## Quick Start\n\n```bash\nwrangler queues create my-queue\nwrangler queues consumer add my-queue my-worker\n```\n\n```typescript\n// Producer\nawait env.MY_QUEUE.send({ userId: 123, action: 'notify' });\n\n// Consumer (with proper error handling)\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n await process(msg.body);\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 60 });\n }\n }\n }\n};\n```\n\n## Critical Warnings\n\n**Before using Queues, understand these production mistakes:**\n\n1. **Uncaught errors retry ENTIRE batch** (not just failed message). Always use per-message try/catch.\n2. **Messages not ack'd/retry'd will auto-retry forever** until max_retries. Always explicitly handle each message.\n\nSee [gotchas.md](./gotchas.md) for detailed solutions.\n\n## Core Operations\n\n| Operation | Purpose | Limit |\n|-----------|---------|-------|\n| `send(body, options?)` | Publish message | 128 KB |\n| `sendBatch(messages)` | Bulk publish | 100 msgs/256 KB |\n| `message.ack()` | Acknowledge success | - |\n| `message.retry(options?)` | Retry with delay | - |\n| `batch.ackAll()` | Ack entire batch | - |\n\n## Architecture\n\n```\n[Producer Worker] → [Queue] → [Consumer Worker/HTTP] → [Processing]\n```\n\n- Max 10,000 queues per account\n- 5,000 msgs/second per queue\n- 4-14 day retention (configurable)\n\n## Reading Order\n\n**New to Queues?** Start here:\n1. [configuration.md](./configuration.md) - Set up queues, bindings, consumers\n2. [api.md](./api.md) - Send messages, handle batches, ack/retry patterns\n3. [patterns.md](./patterns.md) - Real-world examples and integrations\n4. [gotchas.md](./gotchas.md) - Critical warnings and troubleshooting\n\n**Task-based routing:**\n- Setup queue → [configuration.md](./configuration.md)\n- Send/receive messages → [api.md](./api.md)\n- Implement specific pattern → [patterns.md](./patterns.md)\n- Debug/troubleshoot → [gotchas.md](./gotchas.md)\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, producer/consumer config, DLQ, content types\n- [api.md](./api.md) - Send/batch methods, queue handler, ack/retry rules, type-safe patterns\n- [patterns.md](./patterns.md) - Async tasks, buffering, rate limiting, D1/Workflows/DO integrations\n- [gotchas.md](./gotchas.md) - Critical batch error handling, idempotency, error classification\n\n## See Also\n\n- [workers](../workers/) - Worker runtime for producers/consumers\n- [r2](../r2/) - Process R2 event notifications via queues\n- [d1](../d1/) - Batch write to D1 from queue consumers\n" }, { "path": "skills/.curated/cloudflare-deploy/references/queues/api.md", "content": "# Queues API Reference\n\n## Producer: Send Messages\n\n```typescript\n// Basic send\nawait env.MY_QUEUE.send({ url: request.url, timestamp: Date.now() });\n\n// Options: delay (max 43200s), contentType (json|text|bytes|v8)\nawait env.MY_QUEUE.send(message, { delaySeconds: 600 });\nawait env.MY_QUEUE.send(message, { delaySeconds: 0 }); // Override queue default\n\n// Batch (up to 100 msgs or 256 KB)\nawait env.MY_QUEUE.sendBatch([\n { body: 'msg1' },\n { body: 'msg2' },\n { body: 'msg3', options: { delaySeconds: 300 } }\n]);\n\n// Non-blocking with ctx.waitUntil - send continues after response\nctx.waitUntil(env.MY_QUEUE.send({ data: 'async' }));\n\n// Background tasks in queue consumer\nexport default {\n async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise {\n for (const msg of batch.messages) {\n await processMessage(msg.body);\n \n // Fire-and-forget analytics (doesn't block ack)\n ctx.waitUntil(\n env.ANALYTICS_QUEUE.send({ messageId: msg.id, processedAt: Date.now() })\n );\n \n msg.ack();\n }\n }\n};\n```\n\n## Consumer: Push-based (Worker)\n\n```typescript\n// Type-safe handler with ExportedHandler\ninterface Env {\n MY_QUEUE: Queue;\n DB: D1Database;\n}\n\nexport default {\n async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise {\n // batch.queue, batch.messages.length\n for (const msg of batch.messages) {\n // msg.id, msg.body, msg.timestamp, msg.attempts\n try {\n await processMessage(msg.body);\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 600 });\n }\n }\n }\n} satisfies ExportedHandler;\n```\n\n**CRITICAL WARNINGS:**\n\n1. **Messages not explicitly ack'd or retry'd will auto-retry indefinitely** until `max_retries` is reached. Always call `msg.ack()` or `msg.retry()` for each message.\n\n2. **Throwing uncaught errors retries the ENTIRE batch**, not just the failed message. Always wrap individual message processing in try/catch and call `msg.retry()` explicitly per message.\n\n```typescript\n// ❌ BAD: Uncaught error retries entire batch\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n await riskyOperation(msg.body); // If this throws, entire batch retries\n msg.ack();\n }\n}\n\n// ✅ GOOD: Catch per message, handle individually\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n try {\n await riskyOperation(msg.body);\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 60 });\n }\n }\n}\n```\n\n## Ack/Retry Precedence Rules\n\n1. **Per-message calls take precedence**: If you call both `msg.ack()` and `msg.retry()`, last call wins\n2. **Batch calls don't override**: `batch.ackAll()` only affects messages without explicit ack/retry\n3. **No action = automatic retry**: Messages with no explicit action retry with configured delay\n\n```typescript\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n msg.ack(); // Message marked for ack\n msg.retry(); // Overrides ack - message will retry\n }\n \n batch.ackAll(); // Only affects messages not explicitly handled above\n}\n```\n\n## Batch Operations\n\n```typescript\n// Acknowledge entire batch\ntry {\n await bulkProcess(batch.messages);\n batch.ackAll();\n} catch (error) {\n batch.retryAll({ delaySeconds: 300 });\n}\n```\n\n## Exponential Backoff\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n await processMessage(msg.body);\n msg.ack();\n } catch (error) {\n // 30s, 60s, 120s, 240s, 480s, ... up to 12h max\n const delay = Math.min(30 * (2 ** msg.attempts), 43200);\n msg.retry({ delaySeconds: delay });\n }\n }\n}\n```\n\n## Multiple Queues, Single Consumer\n\n```typescript\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n switch (batch.queue) {\n case 'high-priority': await processUrgent(batch.messages); break;\n case 'low-priority': await processDeferred(batch.messages); break;\n case 'email': await sendEmails(batch.messages); break;\n default: batch.retryAll();\n }\n }\n};\n```\n\n## Consumer: Pull-based (HTTP)\n\n```typescript\n// Pull messages\nconst response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull`,\n {\n method: 'POST',\n headers: { 'authorization': `Bearer ${API_TOKEN}`, 'content-type': 'application/json' },\n body: JSON.stringify({ visibility_timeout_ms: 6000, batch_size: 50 })\n }\n);\n\nconst data = await response.json();\n\n// Acknowledge\nawait fetch(\n `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/queues/${QUEUE_ID}/messages/ack`,\n {\n method: 'POST',\n headers: { 'authorization': `Bearer ${API_TOKEN}`, 'content-type': 'application/json' },\n body: JSON.stringify({\n acks: [{ lease_id: msg.lease_id }],\n retries: [{ lease_id: msg2.lease_id, delay_seconds: 600 }]\n })\n }\n);\n```\n\n## Interfaces\n\n```typescript\ninterface MessageBatch {\n readonly queue: string;\n readonly messages: Message[];\n ackAll(): void;\n retryAll(options?: QueueRetryOptions): void;\n}\n\ninterface Message {\n readonly id: string;\n readonly timestamp: Date;\n readonly body: Body;\n readonly attempts: number;\n ack(): void;\n retry(options?: QueueRetryOptions): void;\n}\n\ninterface QueueSendOptions {\n contentType?: 'text' | 'bytes' | 'json' | 'v8';\n delaySeconds?: number; // 0-43200\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/queues/configuration.md", "content": "# Queues Configuration\n\n## Create Queue\n\n```bash\nwrangler queues create my-queue\nwrangler queues create my-queue --retention-period-hours=336 # 14 days\nwrangler queues create my-queue --delivery-delay-secs=300\n```\n\n## Producer Binding\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"queues\": {\n \"producers\": [\n {\n \"queue\": \"my-queue-name\",\n \"binding\": \"MY_QUEUE\",\n \"delivery_delay\": 60 // Optional: default delay in seconds\n }\n ]\n }\n}\n```\n\n## Consumer Configuration (Push-based)\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"queues\": {\n \"consumers\": [\n {\n \"queue\": \"my-queue-name\",\n \"max_batch_size\": 10, // 1-100, default 10\n \"max_batch_timeout\": 5, // 0-60s, default 5\n \"max_retries\": 3, // default 3, max 100\n \"dead_letter_queue\": \"my-dlq\", // optional\n \"retry_delay\": 300 // optional: delay retries in seconds\n }\n ]\n }\n}\n```\n\n## Consumer Configuration (Pull-based)\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"queues\": {\n \"consumers\": [\n {\n \"queue\": \"my-queue-name\",\n \"type\": \"http_pull\",\n \"visibility_timeout_ms\": 5000, // default 30000, max 12h\n \"max_retries\": 5,\n \"dead_letter_queue\": \"my-dlq\"\n }\n ]\n }\n}\n```\n\n## TypeScript Types\n\n```typescript\ninterface Env {\n MY_QUEUE: Queue;\n ANALYTICS_QUEUE: Queue;\n}\n\ninterface MessageBody {\n id: string;\n action: 'create' | 'update' | 'delete';\n data: Record;\n}\n\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n console.log(msg.body.action);\n msg.ack();\n }\n }\n} satisfies ExportedHandler;\n```\n\n## Content Type Selection\n\nChoose content type based on consumer type and data requirements:\n\n| Content Type | Use When | Readable By | Supports | Size |\n|--------------|----------|-------------|----------|------|\n| `json` | Pull consumers, dashboard visibility, simple objects | All (push/pull/dashboard) | JSON-serializable types only | Medium |\n| `v8` | Push consumers only, complex JS objects | Push consumers only | Date, Map, Set, BigInt, typed arrays | Small |\n| `text` | String-only payloads | All | Strings only | Smallest |\n| `bytes` | Binary data (images, files) | All | ArrayBuffer, Uint8Array | Variable |\n\n**Decision tree:**\n1. Need to view in dashboard or use pull consumer? → Use `json`\n2. Need Date, Map, Set, or other V8 types? → Use `v8` (push consumers only)\n3. Just strings? → Use `text`\n4. Binary data? → Use `bytes`\n\n```typescript\n// JSON: Good for simple objects, pull consumers, dashboard visibility\nawait env.QUEUE.send({ id: 123, name: 'test' }, { contentType: 'json' });\n\n// V8: Good for Date, Map, Set (push consumers only)\nawait env.QUEUE.send({ \n created: new Date(), \n tags: new Set(['a', 'b']) \n}, { contentType: 'v8' });\n\n// Text: Simple strings\nawait env.QUEUE.send('process-user-123', { contentType: 'text' });\n\n// Bytes: Binary data\nawait env.QUEUE.send(imageBuffer, { contentType: 'bytes' });\n```\n\n**Default behavior:** If not specified, Cloudflare auto-selects `json` for JSON-serializable objects and `v8` for complex types.\n\n**IMPORTANT:** `v8` messages cannot be read by pull consumers or viewed in the dashboard. Use `json` if you need visibility or pull-based consumption.\n\n## CLI Commands\n\n```bash\n# Consumer management\nwrangler queues consumer add my-queue my-worker --batch-size=50 --max-retries=5\nwrangler queues consumer http add my-queue\nwrangler queues consumer worker remove my-queue my-worker\nwrangler queues consumer http remove my-queue\n\n# Queue operations\nwrangler queues list\nwrangler queues pause my-queue\nwrangler queues resume my-queue\nwrangler queues purge my-queue\nwrangler queues delete my-queue\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/queues/gotchas.md", "content": "# Queues Gotchas & Troubleshooting\n\n## CRITICAL: Top Production Mistakes\n\n### 1. \"Entire Batch Retried After Single Error\"\n\n**Problem:** Throwing uncaught error in queue handler retries the entire batch, not just the failed message \n**Cause:** Uncaught exceptions propagate to the runtime, triggering batch-level retry \n**Solution:** Always wrap individual message processing in try/catch and call `msg.retry()` explicitly\n\n```typescript\n// ❌ BAD: Throws error, retries entire batch\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n await riskyOperation(msg.body); // If this throws, entire batch retries\n msg.ack();\n }\n}\n\n// ✅ GOOD: Catch per message, handle individually\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n try {\n await riskyOperation(msg.body);\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 60 });\n }\n }\n}\n```\n\n### 2. \"Messages Retry Forever\"\n\n**Problem:** Messages not explicitly ack'd or retry'd will auto-retry indefinitely \n**Cause:** Runtime default behavior retries unhandled messages until `max_retries` reached \n**Solution:** Always call `msg.ack()` or `msg.retry()` for each message. Never leave messages unhandled.\n\n```typescript\n// ❌ BAD: Skipped messages auto-retry forever\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n if (shouldProcess(msg.body)) {\n await process(msg.body);\n msg.ack();\n }\n // Missing: msg.ack() for skipped messages - they will retry!\n }\n}\n\n// ✅ GOOD: Explicitly handle all messages\nasync queue(batch: MessageBatch): Promise {\n for (const msg of batch.messages) {\n if (shouldProcess(msg.body)) {\n await process(msg.body);\n msg.ack();\n } else {\n msg.ack(); // Explicitly ack even if not processing\n }\n }\n}\n```\n\n## Common Errors\n\n### \"Duplicate Message Processing\"\n\n**Problem:** Same message processed multiple times \n**Cause:** At-least-once delivery guarantee means duplicates are possible during retries \n**Solution:** Design consumers to be idempotent by tracking processed message IDs in KV with expiration TTL\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n const processed = await env.PROCESSED_KV.get(msg.id);\n if (processed) {\n msg.ack();\n continue;\n }\n \n await processMessage(msg.body);\n await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });\n msg.ack();\n }\n}\n```\n\n### \"Pull Consumer Can't Decode Messages\"\n\n**Problem:** Pull consumer or dashboard shows unreadable message bodies \n**Cause:** Messages sent with `v8` content type are only decodable by Workers push consumers \n**Solution:** Use `json` content type for pull consumers or dashboard visibility\n\n```typescript\n// Use json for pull consumers\nawait env.MY_QUEUE.send(data, { contentType: 'json' });\n\n// Use v8 only for push consumers with complex JS types\nawait env.MY_QUEUE.send({ date: new Date(), tags: new Set() }, { contentType: 'v8' });\n```\n\n### \"Messages Not Being Delivered\"\n\n**Problem:** Messages sent but consumer not processing \n**Cause:** Queue paused, consumer not configured, or consumer errors \n**Solution:** Check queue status with `wrangler queues list`, verify consumer configured with `wrangler queues consumer add`, and check logs with `wrangler tail`\n\n### \"High Dead Letter Queue Rate\"\n\n**Problem:** Many messages ending up in DLQ \n**Cause:** Consumer repeatedly failing to process messages after max retries \n**Solution:** Review consumer error logs, check external dependency availability, verify message format matches expectations, or increase retry delay\n\n## Error Classification Patterns\n\nClassify errors to decide whether to retry or DLQ:\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n await processMessage(msg.body);\n msg.ack();\n } catch (error) {\n // Transient errors: retry with backoff\n if (isRetryable(error)) {\n const delay = Math.min(30 * (2 ** msg.attempts), 43200);\n msg.retry({ delaySeconds: delay });\n } \n // Permanent errors: ack to avoid infinite retries\n else {\n console.error('Permanent error, sending to DLQ:', error);\n await env.ERROR_LOG.put(msg.id, JSON.stringify({ msg: msg.body, error: String(error) }));\n msg.ack(); // Prevent further retries\n }\n }\n }\n}\n\nfunction isRetryable(error: unknown): boolean {\n if (error instanceof Response) {\n // Retry: rate limits, timeouts, server errors\n return error.status === 429 || error.status >= 500;\n }\n if (error instanceof Error) {\n // Don't retry: validation, auth, not found\n return !error.message.includes('validation') && \n !error.message.includes('unauthorized') &&\n !error.message.includes('not found');\n }\n return false; // Unknown errors don't retry\n}\n```\n\n### \"CPU Time Exceeded in Consumer\"\n\n**Problem:** Consumer fails with CPU time limit exceeded \n**Cause:** Consumer processing exceeding 30s default CPU time limit \n**Solution:** Increase CPU limit in wrangler.jsonc: `{ \"limits\": { \"cpu_ms\": 300000 } }` (5 minutes max)\n\n## Content Type Decision Guide\n\n**When to use each content type:**\n\n| Content Type | Use When | Readable By | Supports |\n|--------------|----------|-------------|----------|\n| `json` (default) | Pull consumers, dashboard visibility, simple objects | All (push/pull/dashboard) | JSON-serializable types only |\n| `v8` | Push consumers only, complex JS objects | Push consumers only | Date, Map, Set, BigInt, typed arrays |\n| `text` | String-only payloads | All | Strings only |\n| `bytes` | Binary data (images, files) | All | ArrayBuffer, Uint8Array |\n\n**Decision tree:**\n1. Need to view in dashboard or use pull consumer? → Use `json`\n2. Need Date, Map, Set, or other V8 types? → Use `v8` (push consumers only)\n3. Just strings? → Use `text`\n4. Binary data? → Use `bytes`\n\n```typescript\n// Dashboard/pull: use json\nawait env.QUEUE.send({ id: 123, name: 'test' }, { contentType: 'json' });\n\n// Complex JS types (push only): use v8\nawait env.QUEUE.send({ \n created: new Date(), \n tags: new Set(['a', 'b']) \n}, { contentType: 'v8' });\n```\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Max queues | 10,000 | Per account |\n| Message size | 128 KB | Maximum per message |\n| Batch size (consumer) | 100 messages | Maximum messages per batch |\n| Batch size (sendBatch) | 100 msgs or 256 KB | Whichever limit reached first |\n| Throughput | 5,000 msgs/sec | Per queue |\n| Retention | 4-14 days | Configurable retention period |\n| Max backlog | 25 GB | Maximum queue backlog size |\n| Max delay | 12 hours (43,200s) | Maximum message delay |\n| Max retries | 100 | Maximum retry attempts |\n| CPU time default | 30s | Per consumer invocation |\n| CPU time max | 300s (5 min) | Configurable via `limits.cpu_ms` |\n| Operations per message | 3 (write + read + delete) | Base cost per message |\n| Pricing | $0.40 per 1M operations | After 1M free operations |\n| Message charging | Per 64 KB chunk | Messages charged in 64 KB increments |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/queues/patterns.md", "content": "# Queues Patterns & Best Practices\n\n## Async Task Processing\n\n```typescript\n// Producer: Accept request, queue work\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const { userId, reportType } = await request.json();\n await env.REPORT_QUEUE.send({ userId, reportType, requestedAt: Date.now() });\n return Response.json({ message: 'Report queued', status: 'pending' });\n }\n};\n\n// Consumer: Process reports\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n const { userId, reportType } = msg.body;\n const report = await generateReport(userId, reportType, env);\n await env.REPORTS_BUCKET.put(`${userId}/${reportType}.pdf`, report);\n msg.ack();\n }\n }\n};\n```\n\n## Buffering API Calls\n\n```typescript\n// Producer: Queue log entries\nctx.waitUntil(env.LOGS_QUEUE.send({\n method: request.method,\n url: request.url,\n timestamp: Date.now()\n}));\n\n// Consumer: Batch write to external API\nasync queue(batch: MessageBatch, env: Env): Promise {\n const logs = batch.messages.map(m => m.body);\n await fetch(env.LOG_ENDPOINT, { method: 'POST', body: JSON.stringify({ logs }) });\n batch.ackAll();\n}\n```\n\n## Rate Limiting Upstream\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n await callRateLimitedAPI(msg.body);\n msg.ack();\n } catch (error) {\n if (error.status === 429) {\n const retryAfter = parseInt(error.headers.get('Retry-After') || '60');\n msg.retry({ delaySeconds: retryAfter });\n } else throw error;\n }\n }\n}\n```\n\n## Event-Driven Workflows\n\n```typescript\n// R2 event → Queue → Worker\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n const event = msg.body;\n if (event.action === 'PutObject') {\n await processNewFile(event.object.key, env);\n } else if (event.action === 'DeleteObject') {\n await cleanupReferences(event.object.key, env);\n }\n msg.ack();\n }\n }\n};\n```\n\n## Dead Letter Queue Pattern\n\n```typescript\n// Main queue: After max_retries, goes to DLQ automatically\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n await riskyOperation(msg.body);\n msg.ack();\n } catch (error) {\n console.error(`Failed after ${msg.attempts} attempts:`, error);\n }\n }\n }\n};\n\n// DLQ consumer: Log and store failed messages\nexport default {\n async queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n await env.FAILED_KV.put(msg.id, JSON.stringify(msg.body));\n msg.ack();\n }\n }\n};\n```\n\n## Priority Queues\n\nHigh priority: `max_batch_size: 5, max_batch_timeout: 1`. Low priority: `max_batch_size: 100, max_batch_timeout: 30`.\n\n## Delayed Job Processing\n\n```typescript\nawait env.EMAIL_QUEUE.send({ to, template, userId }, { delaySeconds: 3600 });\n```\n\n## Fan-out Pattern\n\n```typescript\nasync fetch(request: Request, env: Env): Promise {\n const event = await request.json();\n \n // Send to multiple queues for parallel processing\n await Promise.all([\n env.ANALYTICS_QUEUE.send(event),\n env.NOTIFICATIONS_QUEUE.send(event),\n env.AUDIT_LOG_QUEUE.send(event)\n ]);\n \n return Response.json({ status: 'processed' });\n}\n```\n\n## Idempotency Pattern\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n // Check if already processed\n const processed = await env.PROCESSED_KV.get(msg.id);\n if (processed) {\n msg.ack();\n continue;\n }\n \n await processMessage(msg.body);\n await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });\n msg.ack();\n }\n}\n```\n\n## Integration: D1 Batch Writes\n\n```typescript\nasync queue(batch: MessageBatch, env: Env): Promise {\n // Collect all inserts for single D1 batch\n const statements = batch.messages.map(msg => \n env.DB.prepare('INSERT INTO events (id, data, created) VALUES (?, ?, ?)')\n .bind(msg.id, JSON.stringify(msg.body), Date.now())\n );\n \n try {\n await env.DB.batch(statements);\n batch.ackAll();\n } catch (error) {\n console.error('D1 batch failed:', error);\n batch.retryAll({ delaySeconds: 60 });\n }\n}\n```\n\n## Integration: Workflows\n\n```typescript\n// Queue triggers Workflow for long-running tasks\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n try {\n const instance = await env.MY_WORKFLOW.create({\n id: msg.id,\n params: msg.body\n });\n console.log('Workflow started:', instance.id);\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 30 });\n }\n }\n}\n```\n\n## Integration: Durable Objects\n\n```typescript\n// Queue distributes work to Durable Objects by ID\nasync queue(batch: MessageBatch, env: Env): Promise {\n for (const msg of batch.messages) {\n const { userId, action } = msg.body;\n \n // Route to user-specific DO\n const id = env.USER_DO.idFromName(userId);\n const stub = env.USER_DO.get(id);\n \n try {\n await stub.fetch(new Request('https://do/process', {\n method: 'POST',\n body: JSON.stringify({ action, messageId: msg.id })\n }));\n msg.ack();\n } catch (error) {\n msg.retry({ delaySeconds: 60 });\n }\n }\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2/README.md", "content": "# Cloudflare R2 Object Storage\n\nS3-compatible object storage with zero egress fees, optimized for large file storage and delivery.\n\n## Overview\n\nR2 provides:\n- S3-compatible API (Workers API + S3 REST)\n- Zero egress fees globally\n- Strong consistency for writes/deletes\n- Storage classes (Standard/Infrequent Access)\n- SSE-C encryption support\n\n**Use cases:** Media storage, backups, static assets, user uploads, data lakes\n\n## Quick Start\n\n```bash\nwrangler r2 bucket create my-bucket --location=enam\nwrangler r2 object put my-bucket/file.txt --file=./local.txt\n```\n\n```typescript\n// Upload\nawait env.MY_BUCKET.put(key, data, {\n httpMetadata: { contentType: 'image/jpeg' }\n});\n\n// Download\nconst object = await env.MY_BUCKET.get(key);\nif (object) return new Response(object.body);\n```\n\n## Core Operations\n\n| Method | Purpose | Returns |\n|--------|---------|---------|\n| `put(key, value, options?)` | Upload object | `R2Object \\| null` |\n| `get(key, options?)` | Download object | `R2ObjectBody \\| R2Object \\| null` |\n| `head(key)` | Get metadata only | `R2Object \\| null` |\n| `delete(keys)` | Delete object(s) | `Promise` |\n| `list(options?)` | List objects | `R2Objects` |\n\n## Storage Classes\n\n- **Standard**: Frequent access, low latency reads\n- **InfrequentAccess**: 30-day minimum storage, retrieval fees, lower storage cost\n\n## Event Notifications\n\nR2 integrates with Cloudflare Queues for reactive workflows:\n\n```typescript\n// wrangler.jsonc\n{\n \"event_notifications\": [{\n \"queue\": \"r2-notifications\",\n \"actions\": [\"PutObject\", \"DeleteObject\"]\n }]\n}\n\n// Consumer\nasync queue(batch: MessageBatch, env: Env) {\n for (const message of batch.messages) {\n const event = message.body; // { action, bucket, object, timestamps }\n if (event.action === 'PutObject') {\n // Process upload: thumbnail generation, virus scan, etc.\n }\n }\n}\n```\n\n## Reading Order\n\n**First-time users:** README → configuration.md → api.md → patterns.md \n**Specific tasks:**\n- Setup: configuration.md\n- Client uploads: patterns.md (presigned URLs)\n- Public static site: patterns.md (public access + custom domain)\n- Processing uploads: README (event notifications) + queues reference\n- Debugging: gotchas.md\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - Bindings, S3 SDK, CORS, lifecycles, token scopes\n- [api.md](./api.md) - Workers API, multipart, conditional requests, presigned URLs\n- [patterns.md](./patterns.md) - Streaming, caching, client uploads, public buckets\n- [gotchas.md](./gotchas.md) - List truncation, etag format, stream length, S3 SDK region\n\n## See Also\n\n- [workers](../workers/) - Worker runtime and fetch handlers\n- [kv](../kv/) - Metadata storage for R2 objects\n- [d1](../d1/) - Store R2 URLs in relational database\n- [queues](../queues/) - Process R2 uploads asynchronously\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2/api.md", "content": "# R2 API Reference\n\n## PUT (Upload)\n\n```typescript\n// Basic\nawait env.MY_BUCKET.put(key, value);\n\n// With metadata\nawait env.MY_BUCKET.put(key, value, {\n httpMetadata: {\n contentType: 'image/jpeg',\n contentDisposition: 'attachment; filename=\"photo.jpg\"',\n cacheControl: 'max-age=3600'\n },\n customMetadata: { userId: '123', version: '2' },\n storageClass: 'Standard', // or 'InfrequentAccess'\n sha256: arrayBufferOrHex, // Integrity check\n ssecKey: arrayBuffer32bytes // SSE-C encryption\n});\n\n// Value types: ReadableStream | ArrayBuffer | string | Blob\n```\n\n## GET (Download)\n\n```typescript\nconst object = await env.MY_BUCKET.get(key);\nif (!object) return new Response('Not found', { status: 404 });\n\n// Body: arrayBuffer(), text(), json(), blob(), body (ReadableStream)\n\n// Ranged reads\nconst object = await env.MY_BUCKET.get(key, { range: { offset: 0, length: 1024 } });\n\n// Conditional GET\nconst object = await env.MY_BUCKET.get(key, { onlyIf: { etagMatches: '\"abc123\"' } });\n```\n\n## HEAD (Metadata Only)\n\n```typescript\nconst object = await env.MY_BUCKET.head(key); // Returns R2Object without body\n```\n\n## DELETE\n\n```typescript\nawait env.MY_BUCKET.delete(key);\nawait env.MY_BUCKET.delete([key1, key2, key3]); // Batch (max 1000)\n```\n## LIST\n\n```typescript\nconst listed = await env.MY_BUCKET.list({\n limit: 1000,\n prefix: 'photos/',\n cursor: cursorFromPrevious,\n delimiter: '/',\n include: ['httpMetadata', 'customMetadata']\n});\n\n// Pagination (always use truncated flag)\nwhile (listed.truncated) {\n const next = await env.MY_BUCKET.list({ cursor: listed.cursor });\n listed.objects.push(...next.objects);\n listed.truncated = next.truncated;\n listed.cursor = next.cursor;\n}\n```\n\n## Multipart Uploads\n\n```typescript\nconst multipart = await env.MY_BUCKET.createMultipartUpload(key, {\n httpMetadata: { contentType: 'video/mp4' }\n});\n\nconst uploadedParts: R2UploadedPart[] = [];\nfor (let i = 0; i < partCount; i++) {\n const part = await multipart.uploadPart(i + 1, partData);\n uploadedParts.push(part);\n}\n\nconst object = await multipart.complete(uploadedParts);\n// OR: await multipart.abort();\n\n// Resume\nconst multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);\n```\n\n## Presigned URLs (S3 SDK)\n\n```typescript\nimport { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner';\n\nconst s3 = new S3Client({\n region: 'auto',\n endpoint: `https://${accountId}.r2.cloudflarestorage.com`,\n credentials: { accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY }\n});\n\nconst uploadUrl = await getSignedUrl(s3, new PutObjectCommand({ Bucket: 'my-bucket', Key: key }), { expiresIn: 3600 });\nreturn Response.json({ uploadUrl });\n```\n\n## TypeScript Interfaces\n\n```typescript\ninterface R2Bucket {\n head(key: string): Promise;\n get(key: string, options?: R2GetOptions): Promise;\n put(key: string, value: ReadableStream | ArrayBuffer | string | Blob, options?: R2PutOptions): Promise;\n delete(keys: string | string[]): Promise;\n list(options?: R2ListOptions): Promise;\n createMultipartUpload(key: string, options?: R2MultipartOptions): Promise;\n resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload;\n}\n\ninterface R2Object {\n key: string; version: string; size: number;\n etag: string; httpEtag: string; // httpEtag is quoted, use for headers\n uploaded: Date; httpMetadata?: R2HTTPMetadata;\n customMetadata?: Record;\n storageClass: 'Standard' | 'InfrequentAccess';\n checksums: R2Checksums;\n writeHttpMetadata(headers: Headers): void;\n}\n\ninterface R2ObjectBody extends R2Object {\n body: ReadableStream; bodyUsed: boolean;\n arrayBuffer(): Promise; text(): Promise;\n json(): Promise; blob(): Promise;\n}\n\ninterface R2HTTPMetadata {\n contentType?: string; contentDisposition?: string;\n contentEncoding?: string; contentLanguage?: string;\n cacheControl?: string; cacheExpiry?: Date;\n}\n\ninterface R2PutOptions {\n httpMetadata?: R2HTTPMetadata | Headers;\n customMetadata?: Record;\n sha256?: ArrayBuffer | string; // Only ONE checksum allowed\n storageClass?: 'Standard' | 'InfrequentAccess';\n ssecKey?: ArrayBuffer;\n}\n\ninterface R2GetOptions {\n onlyIf?: R2Conditional | Headers;\n range?: R2Range | Headers;\n ssecKey?: ArrayBuffer;\n}\n\ninterface R2ListOptions {\n limit?: number; prefix?: string; cursor?: string; delimiter?: string;\n startAfter?: string; include?: ('httpMetadata' | 'customMetadata')[];\n}\n\ninterface R2Objects {\n objects: R2Object[]; truncated: boolean;\n cursor?: string; delimitedPrefixes: string[];\n}\n\ninterface R2Conditional {\n etagMatches?: string; etagDoesNotMatch?: string;\n uploadedBefore?: Date; uploadedAfter?: Date;\n}\n\ninterface R2Range { offset?: number; length?: number; suffix?: number; }\n\ninterface R2Checksums {\n md5?: ArrayBuffer; sha1?: ArrayBuffer; sha256?: ArrayBuffer;\n sha384?: ArrayBuffer; sha512?: ArrayBuffer;\n}\n\ninterface R2MultipartUpload {\n key: string;\n uploadId: string;\n uploadPart(partNumber: number, value: ReadableStream | ArrayBuffer | string | Blob): Promise;\n abort(): Promise;\n complete(uploadedParts: R2UploadedPart[]): Promise;\n}\n\ninterface R2UploadedPart {\n partNumber: number;\n etag: string;\n}\n```\n\n## CLI Operations\n\n```bash\nwrangler r2 object put my-bucket/file.txt --file=./local.txt\nwrangler r2 object get my-bucket/file.txt --file=./download.txt\nwrangler r2 object delete my-bucket/file.txt\nwrangler r2 object list my-bucket --prefix=photos/\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2/configuration.md", "content": "# R2 Configuration\n\n## Workers Binding\n\n**wrangler.jsonc:**\n```jsonc\n{\n \"r2_buckets\": [\n {\n \"binding\": \"MY_BUCKET\",\n \"bucket_name\": \"my-bucket-name\"\n }\n ]\n}\n```\n\n## TypeScript Types\n\n```typescript\ninterface Env { MY_BUCKET: R2Bucket; }\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const object = await env.MY_BUCKET.get('file.txt');\n return new Response(object?.body);\n }\n}\n```\n\n## S3 SDK Setup\n\n```typescript\nimport { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';\n\nconst s3 = new S3Client({\n region: 'auto',\n endpoint: `https://${accountId}.r2.cloudflarestorage.com`,\n credentials: {\n accessKeyId: env.R2_ACCESS_KEY_ID,\n secretAccessKey: env.R2_SECRET_ACCESS_KEY\n }\n});\n\nawait s3.send(new PutObjectCommand({\n Bucket: 'my-bucket',\n Key: 'file.txt',\n Body: data,\n StorageClass: 'STANDARD' // or 'STANDARD_IA'\n}));\n```\n\n## Location Hints\n\n```bash\nwrangler r2 bucket create my-bucket --location=enam\n\n# Hints: wnam, enam, weur, eeur, apac, oc\n# Jurisdictions (override hint): --jurisdiction=eu (or fedramp)\n```\n\n## CORS Configuration\n\nCORS must be configured via S3 SDK or dashboard (not available in Workers API):\n\n```typescript\nimport { S3Client, PutBucketCorsCommand } from '@aws-sdk/client-s3';\n\nconst s3 = new S3Client({\n region: 'auto',\n endpoint: `https://${accountId}.r2.cloudflarestorage.com`,\n credentials: {\n accessKeyId: env.R2_ACCESS_KEY_ID,\n secretAccessKey: env.R2_SECRET_ACCESS_KEY\n }\n});\n\nawait s3.send(new PutBucketCorsCommand({\n Bucket: 'my-bucket',\n CORSConfiguration: {\n CORSRules: [{\n AllowedOrigins: ['https://example.com'],\n AllowedMethods: ['GET', 'PUT', 'HEAD'],\n AllowedHeaders: ['*'],\n ExposeHeaders: ['ETag'],\n MaxAgeSeconds: 3600\n }]\n }\n}));\n```\n\n## Object Lifecycles\n\n```typescript\nimport { PutBucketLifecycleConfigurationCommand } from '@aws-sdk/client-s3';\n\nawait s3.send(new PutBucketLifecycleConfigurationCommand({\n Bucket: 'my-bucket',\n LifecycleConfiguration: {\n Rules: [\n {\n ID: 'expire-old-logs',\n Status: 'Enabled',\n Prefix: 'logs/',\n Expiration: { Days: 90 }\n },\n {\n ID: 'transition-to-ia',\n Status: 'Enabled',\n Prefix: 'archives/',\n Transitions: [{ Days: 30, StorageClass: 'STANDARD_IA' }]\n }\n ]\n }\n}));\n```\n\n## API Token Scopes\n\nWhen creating R2 tokens, set minimal permissions:\n\n| Permission | Use Case |\n|------------|----------|\n| Object Read | Public serving, downloads |\n| Object Write | Uploads only |\n| Object Read & Write | Full object operations |\n| Admin Read & Write | Bucket management, CORS, lifecycles |\n\n**Best practice:** Separate tokens for Workers (read/write) vs admin tasks (CORS, lifecycles).\n\n## Event Notifications\n\n```jsonc\n// wrangler.jsonc\n{\n \"r2_buckets\": [\n {\n \"binding\": \"MY_BUCKET\",\n \"bucket_name\": \"my-bucket\",\n \"event_notifications\": [\n {\n \"queue\": \"r2-events\",\n \"actions\": [\"PutObject\", \"DeleteObject\", \"CompleteMultipartUpload\"]\n }\n ]\n }\n ],\n \"queues\": {\n \"producers\": [{ \"binding\": \"R2_EVENTS\", \"queue\": \"r2-events\" }],\n \"consumers\": [{ \"queue\": \"r2-events\", \"max_batch_size\": 10 }]\n }\n}\n```\n\n## Bucket Management\n\n```bash\nwrangler r2 bucket create my-bucket --location=enam --storage-class=Standard\nwrangler r2 bucket list\nwrangler r2 bucket info my-bucket\nwrangler r2 bucket delete my-bucket # Must be empty\nwrangler r2 bucket update-storage-class my-bucket --storage-class=InfrequentAccess\n\n# Public bucket via dashboard\nwrangler r2 bucket domain add my-bucket --domain=files.example.com\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2/gotchas.md", "content": "# R2 Gotchas & Troubleshooting\n\n## List Truncation\n\n```typescript\n// ❌ WRONG: Don't compare object count when using include\nwhile (listed.objects.length < options.limit) { ... }\n\n// ✅ CORRECT: Always use truncated property\nwhile (listed.truncated) {\n const next = await env.MY_BUCKET.list({ cursor: listed.cursor });\n // ...\n}\n```\n\n**Reason:** `include` with metadata may return fewer objects per page to fit metadata.\n\n## ETag Format\n\n```typescript\n// ❌ WRONG: Using etag (unquoted) in headers\nheaders.set('etag', object.etag); // Missing quotes\n\n// ✅ CORRECT: Use httpEtag (quoted)\nheaders.set('etag', object.httpEtag);\n```\n\n## Checksum Limits\n\nOnly ONE checksum algorithm allowed per PUT:\n\n```typescript\n// ❌ WRONG: Multiple checksums\nawait env.MY_BUCKET.put(key, data, { md5: hash1, sha256: hash2 }); // Error\n\n// ✅ CORRECT: Pick one\nawait env.MY_BUCKET.put(key, data, { sha256: hash });\n```\n\n## Multipart Requirements\n\n- All parts must be uniform size (except last part)\n- Part numbers start at 1 (not 0)\n- Uncompleted uploads auto-abort after 7 days\n- `resumeMultipartUpload` doesn't validate uploadId existence\n\n## Conditional Operations\n\n```typescript\n// Precondition failure returns object WITHOUT body\nconst object = await env.MY_BUCKET.get(key, {\n onlyIf: { etagMatches: '\"wrong\"' }\n});\n\n// Check for body, not just null\nif (!object) return new Response('Not found', { status: 404 });\nif (!object.body) return new Response(null, { status: 304 }); // Precondition failed\n```\n\n## Key Validation\n\n```typescript\n// ❌ DANGEROUS: Path traversal\nconst key = url.pathname.slice(1); // Could be ../../../etc/passwd\nawait env.MY_BUCKET.get(key);\n\n// ✅ SAFE: Validate keys\nif (!key || key.includes('..') || key.startsWith('/')) {\n return new Response('Invalid key', { status: 400 });\n}\n```\n\n## Storage Class Pitfalls\n\n- InfrequentAccess: 30-day minimum billing (even if deleted early)\n- Can't transition IA → Standard via lifecycle (use S3 CopyObject)\n- Retrieval fees apply for IA reads\n\n## Stream Length Requirement\n\n```typescript\n// ❌ WRONG: Streaming unknown length fails silently\nconst response = await fetch(url);\nawait env.MY_BUCKET.put(key, response.body); // May fail without error\n\n// ✅ CORRECT: Buffer or use Content-Length\nconst data = await response.arrayBuffer();\nawait env.MY_BUCKET.put(key, data);\n\n// OR: Pass Content-Length if known\nconst object = await env.MY_BUCKET.put(key, request.body, {\n httpMetadata: {\n contentLength: parseInt(request.headers.get('content-length') || '0')\n }\n});\n```\n\n**Reason:** R2 requires known length for streams. Unknown length may cause silent truncation.\n\n## S3 SDK Region Configuration\n\n```typescript\n// ❌ WRONG: Missing region breaks ALL S3 SDK calls\nconst s3 = new S3Client({\n endpoint: `https://${accountId}.r2.cloudflarestorage.com`,\n credentials: { ... }\n});\n\n// ✅ CORRECT: MUST set region='auto'\nconst s3 = new S3Client({\n region: 'auto', // REQUIRED\n endpoint: `https://${accountId}.r2.cloudflarestorage.com`,\n credentials: { ... }\n});\n```\n\n**Reason:** S3 SDK requires region. R2 uses 'auto' as placeholder.\n\n## Local Development Limits\n\n```typescript\n// ❌ Miniflare/wrangler dev: Limited R2 support\n// - No multipart uploads\n// - No presigned URLs (requires S3 SDK + network)\n// - Memory-backed storage (lost on restart)\n\n// ✅ Use remote bindings for full features\nwrangler dev --remote\n\n// OR: Conditional logic\nif (env.ENVIRONMENT === 'development') {\n // Fallback for local dev\n} else {\n // Full R2 features\n}\n```\n\n## Presigned URL Expiry\n\n```typescript\n// ❌ WRONG: URL expires but no client validation\nconst url = await getSignedUrl(s3, command, { expiresIn: 60 });\n// 61 seconds later: 403 Forbidden\n\n// ✅ CORRECT: Return expiry to client\nreturn Response.json({\n uploadUrl: url,\n expiresAt: new Date(Date.now() + 60000).toISOString()\n});\n```\n\n## Limits\n\n| Limit | Value |\n|-------|-------|\n| Object size | 5 TB |\n| Multipart part count | 10,000 |\n| Multipart part min size | 5 MB (except last) |\n| Batch delete | 1,000 keys |\n| List limit | 1,000 per request |\n| Key size | 1024 bytes |\n| Custom metadata | 2 KB per object |\n| Presigned URL max expiry | 7 days |\n\n## Common Errors\n\n### \"Stream upload failed\" / Silent Truncation\n\n**Cause:** Stream length unknown or Content-Length missing \n**Solution:** Buffer data or pass explicit Content-Length\n\n### \"Invalid credentials\" / S3 SDK\n\n**Cause:** Missing `region: 'auto'` in S3Client config \n**Solution:** Always set `region: 'auto'` for R2\n\n### \"Object not found\"\n\n**Cause:** Object key doesn't exist or was deleted \n**Solution:** Verify object key correct, check if object was deleted, ensure bucket correct\n\n### \"List compatibility error\"\n\n**Cause:** Missing or old compatibility_date, or flag not enabled \n**Solution:** Set `compatibility_date >= 2022-08-04` or enable `r2_list_honor_include` flag\n\n### \"Multipart upload failed\"\n\n**Cause:** Part sizes not uniform or incorrect part number \n**Solution:** Ensure uniform size except final part, verify part numbers start at 1\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2/patterns.md", "content": "# R2 Patterns & Best Practices\n\n## Streaming Large Files\n\n```typescript\nconst object = await env.MY_BUCKET.get(key);\nif (!object) return new Response('Not found', { status: 404 });\n\nconst headers = new Headers();\nobject.writeHttpMetadata(headers);\nheaders.set('etag', object.httpEtag);\n\nreturn new Response(object.body, { headers });\n```\n\n## Conditional GET (304 Not Modified)\n\n```typescript\nconst ifNoneMatch = request.headers.get('if-none-match');\nconst object = await env.MY_BUCKET.get(key, {\n onlyIf: { etagDoesNotMatch: ifNoneMatch?.replace(/\"/g, '') || '' }\n});\n\nif (!object) return new Response('Not found', { status: 404 });\nif (!object.body) return new Response(null, { status: 304, headers: { 'etag': object.httpEtag } });\n\nreturn new Response(object.body, { headers: { 'etag': object.httpEtag } });\n```\n\n## Upload with Validation\n\n```typescript\nconst key = url.pathname.slice(1);\nif (!key || key.includes('..')) return new Response('Invalid key', { status: 400 });\n\nconst object = await env.MY_BUCKET.put(key, request.body, {\n httpMetadata: { contentType: request.headers.get('content-type') || 'application/octet-stream' },\n customMetadata: { uploadedAt: new Date().toISOString(), ip: request.headers.get('cf-connecting-ip') || 'unknown' }\n});\n\nreturn Response.json({ key: object.key, size: object.size, etag: object.httpEtag });\n```\n\n## Multipart with Progress\n\n```typescript\nconst PART_SIZE = 5 * 1024 * 1024; // 5MB\nconst partCount = Math.ceil(file.size / PART_SIZE);\nconst multipart = await env.MY_BUCKET.createMultipartUpload(key, { httpMetadata: { contentType: file.type } });\n\nconst uploadedParts: R2UploadedPart[] = [];\ntry {\n for (let i = 0; i < partCount; i++) {\n const start = i * PART_SIZE;\n const part = await multipart.uploadPart(i + 1, file.slice(start, start + PART_SIZE));\n uploadedParts.push(part);\n onProgress?.(Math.round(((i + 1) / partCount) * 100));\n }\n return await multipart.complete(uploadedParts);\n} catch (error) {\n await multipart.abort();\n throw error;\n}\n```\n\n## Batch Delete\n\n```typescript\nasync function deletePrefix(prefix: string, env: Env) {\n let cursor: string | undefined;\n let truncated = true;\n\n while (truncated) {\n const listed = await env.MY_BUCKET.list({ prefix, limit: 1000, cursor });\n if (listed.objects.length > 0) {\n await env.MY_BUCKET.delete(listed.objects.map(o => o.key));\n }\n truncated = listed.truncated;\n cursor = listed.cursor;\n }\n}\n```\n\n## Checksum Validation & Storage Transitions\n\n```typescript\n// Upload with checksum\nconst hash = await crypto.subtle.digest('SHA-256', data);\nawait env.MY_BUCKET.put(key, data, { sha256: hash });\n\n// Transition storage class (requires S3 SDK)\nimport { S3Client, CopyObjectCommand } from '@aws-sdk/client-s3';\nawait s3.send(new CopyObjectCommand({\n Bucket: 'my-bucket', Key: key,\n CopySource: `/my-bucket/${key}`,\n StorageClass: 'STANDARD_IA'\n}));\n```\n\n## Client-Side Uploads (Presigned URLs)\n\n```typescript\nimport { S3Client } from '@aws-sdk/client-s3';\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner';\nimport { PutObjectCommand } from '@aws-sdk/client-s3';\n\n// Worker: Generate presigned upload URL\nconst s3 = new S3Client({\n region: 'auto',\n endpoint: `https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com`,\n credentials: { accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY }\n});\n\nconst url = await getSignedUrl(s3, new PutObjectCommand({ Bucket: 'my-bucket', Key: key }), { expiresIn: 3600 });\nreturn Response.json({ uploadUrl: url });\n\n// Client: Upload directly\nconst { uploadUrl } = await fetch('/api/upload-url').then(r => r.json());\nawait fetch(uploadUrl, { method: 'PUT', body: file });\n```\n\n## Caching with Cache API\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const cache = caches.default;\n const url = new URL(request.url);\n const cacheKey = new Request(url.toString(), request);\n\n // Check cache first\n let response = await cache.match(cacheKey);\n if (response) return response;\n\n // Fetch from R2\n const key = url.pathname.slice(1);\n const object = await env.MY_BUCKET.get(key);\n if (!object) return new Response('Not found', { status: 404 });\n\n const headers = new Headers();\n object.writeHttpMetadata(headers);\n headers.set('etag', object.httpEtag);\n headers.set('cache-control', 'public, max-age=31536000, immutable');\n\n response = new Response(object.body, { headers });\n\n // Cache for subsequent requests\n ctx.waitUntil(cache.put(cacheKey, response.clone()));\n\n return response;\n }\n};\n```\n\n## Public Bucket with Custom Domain\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // CORS preflight\n if (request.method === 'OPTIONS') {\n return new Response(null, {\n headers: {\n 'access-control-allow-origin': '*',\n 'access-control-allow-methods': 'GET, HEAD',\n 'access-control-max-age': '86400'\n }\n });\n }\n\n const key = new URL(request.url).pathname.slice(1);\n if (!key) return Response.redirect('/index.html', 302);\n\n const object = await env.MY_BUCKET.get(key);\n if (!object) return new Response('Not found', { status: 404 });\n\n const headers = new Headers();\n object.writeHttpMetadata(headers);\n headers.set('etag', object.httpEtag);\n headers.set('access-control-allow-origin', '*');\n headers.set('cache-control', 'public, max-age=31536000, immutable');\n\n return new Response(object.body, { headers });\n }\n};\n```\n\n## r2.dev Public URLs\n\nEnable r2.dev in dashboard for simple public access: `https://pub-${hashId}.r2.dev/${key}` \nOr add custom domain via dashboard: `https://files.example.com/${key}`\n\n**Limitations:** No auth, bucket-level CORS, no cache override.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-data-catalog/README.md", "content": "# Cloudflare R2 Data Catalog Skill Reference\n\nExpert guidance for Cloudflare R2 Data Catalog - Apache Iceberg catalog built into R2 buckets.\n\n## Reading Order\n\n**New to R2 Data Catalog?** Start here:\n1. Read \"What is R2 Data Catalog?\" and \"When to Use\" below\n2. [configuration.md](configuration.md) - Enable catalog, create tokens\n3. [patterns.md](patterns.md) - PyIceberg setup and common patterns\n4. [api.md](api.md) - REST API reference as needed\n5. [gotchas.md](gotchas.md) - Troubleshooting when issues arise\n\n**Quick reference?** Jump to:\n- [Enable catalog on bucket](configuration.md#enable-catalog-on-bucket)\n- [PyIceberg connection pattern](patterns.md#pyiceberg-connection-pattern)\n- [Permission errors](gotchas.md#permission-errors)\n\n## What is R2 Data Catalog?\n\nR2 Data Catalog is a **managed Apache Iceberg REST catalog** built directly into R2 buckets. It provides:\n\n- **Apache Iceberg tables** - ACID transactions, schema evolution, time-travel queries\n- **Zero-egress costs** - Query from any cloud/region without data transfer fees\n- **Standard REST API** - Works with Spark, PyIceberg, Snowflake, Trino, DuckDB\n- **No infrastructure** - Fully managed, no catalog servers to run\n- **Public beta** - Available to all R2 subscribers, no extra cost beyond R2 storage\n\n### What is Apache Iceberg?\n\nOpen table format for analytics datasets in object storage. Features:\n- **ACID transactions** - Safe concurrent reads/writes\n- **Metadata optimization** - Fast queries without full scans\n- **Schema evolution** - Add/rename/delete columns without rewrites\n- **Time-travel** - Query historical snapshots\n- **Partitioning** - Organize data for efficient queries\n\n## When to Use\n\n**Use R2 Data Catalog for:**\n- **Log analytics** - Store and query application/system logs\n- **Data lakes/warehouses** - Analytical datasets queried by multiple engines\n- **BI pipelines** - Aggregate data for dashboards and reports\n- **Multi-cloud analytics** - Share data across clouds without egress fees\n- **Time-series data** - Event streams, metrics, sensor data\n\n**Don't use for:**\n- **Transactional workloads** - Use D1 or external database instead\n- **Sub-second latency** - Iceberg optimized for batch/analytical queries\n- **Small datasets (<1GB)** - Setup overhead not worth it\n- **Unstructured data** - Store files directly in R2, not as Iceberg tables\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│ Query Engines │\n│ (PyIceberg, Spark, Trino, Snowflake, DuckDB) │\n└────────────────┬────────────────────────────────┘\n │\n │ REST API (OAuth2 token)\n ▼\n┌─────────────────────────────────────────────────┐\n│ R2 Data Catalog (Managed Iceberg REST Catalog)│\n│ • Namespace/table metadata │\n│ • Transaction coordination │\n│ • Snapshot management │\n└────────────────┬────────────────────────────────┘\n │\n │ Vended credentials\n ▼\n┌─────────────────────────────────────────────────┐\n│ R2 Bucket Storage │\n│ • Parquet data files │\n│ • Metadata files │\n│ • Manifest files │\n└─────────────────────────────────────────────────┘\n```\n\n**Key concepts:**\n- **Catalog URI** - REST endpoint for catalog operations (e.g., `https://.r2.cloudflarestorage.com/iceberg/`)\n- **Warehouse** - Logical grouping of tables (typically same as bucket name)\n- **Namespace** - Schema/database containing tables (e.g., `logs`, `analytics`)\n- **Table** - Iceberg table with schema, data files, snapshots\n- **Vended credentials** - Temporary S3 credentials catalog provides for data access\n\n## Limits\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| Namespaces per catalog | No hard limit | Organize tables logically |\n| Tables per namespace | <10,000 recommended | Performance degrades beyond this |\n| Files per table | <100,000 recommended | Run compaction regularly |\n| Snapshots per table | Configurable retention | Expire >7 days old |\n| Partitions per table | 100-1,000 optimal | Too many = slow metadata ops |\n| Table size | Same as R2 bucket | 10GB-10TB+ common |\n| API rate limits | Standard R2 API limits | Shared with R2 storage operations |\n| Target file size | 128-512 MB | After compaction |\n\n## Current Status\n\n**Public Beta** (as of Jan 2026)\n- Available to all R2 subscribers\n- No extra cost beyond standard R2 storage/operations\n- Production-ready, but breaking changes possible\n- Supports: namespaces, tables, snapshots, compaction, time-travel, table maintenance\n\n## Decision Tree: Is R2 Data Catalog Right For You?\n\n```\nStart → Need analytics on object storage data?\n │\n ├─ No → Use R2 directly for object storage\n │\n └─ Yes → Dataset >1GB with structured schema?\n │\n ├─ No → Too small, use R2 + ad-hoc queries\n │\n └─ Yes → Need ACID transactions or schema evolution?\n │\n ├─ No → Consider simpler solutions (Parquet on R2)\n │\n └─ Yes → Need multi-cloud/multi-tool access?\n │\n ├─ No → D1 or external DB may be simpler\n │\n └─ Yes → ✅ Use R2 Data Catalog\n```\n\n**Quick check:** If you answer \"yes\" to all:\n- Dataset >1GB and growing\n- Structured/tabular data (logs, events, metrics)\n- Multiple query tools or cloud environments\n- Need versioning, schema changes, or concurrent access\n\n→ R2 Data Catalog is a good fit.\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Enable catalog, create API tokens, connect clients\n- **[api.md](api.md)** - REST endpoints, operations, maintenance\n- **[patterns.md](patterns.md)** - PyIceberg examples, common use cases\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations\n\n## See Also\n\n- [Cloudflare R2 Data Catalog Docs](https://developers.cloudflare.com/r2/data-catalog/)\n- [Apache Iceberg Docs](https://iceberg.apache.org/)\n- [PyIceberg Docs](https://py.iceberg.apache.org/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-data-catalog/api.md", "content": "# API Reference\n\nR2 Data Catalog exposes standard [Apache Iceberg REST Catalog API](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml).\n\n## Quick Reference\n\n**Most common operations:**\n\n| Task | PyIceberg Code |\n|------|----------------|\n| Connect | `RestCatalog(name=\"r2\", warehouse=bucket, uri=uri, token=token)` |\n| List namespaces | `catalog.list_namespaces()` |\n| Create namespace | `catalog.create_namespace(\"logs\")` |\n| Create table | `catalog.create_table((\"ns\", \"table\"), schema=schema)` |\n| Load table | `catalog.load_table((\"ns\", \"table\"))` |\n| Append data | `table.append(pyarrow_table)` |\n| Query data | `table.scan().to_pandas()` |\n| Compact files | `table.rewrite_data_files(target_file_size_bytes=128*1024*1024)` |\n| Expire snapshots | `table.expire_snapshots(older_than=timestamp_ms, retain_last=10)` |\n\n## REST Endpoints\n\nBase: `https://.r2.cloudflarestorage.com/iceberg/`\n\n| Operation | Method | Path |\n|-----------|--------|------|\n| Catalog config | GET | `/v1/config` |\n| List namespaces | GET | `/v1/namespaces` |\n| Create namespace | POST | `/v1/namespaces` |\n| Delete namespace | DELETE | `/v1/namespaces/{ns}` |\n| List tables | GET | `/v1/namespaces/{ns}/tables` |\n| Create table | POST | `/v1/namespaces/{ns}/tables` |\n| Load table | GET | `/v1/namespaces/{ns}/tables/{table}` |\n| Update table | POST | `/v1/namespaces/{ns}/tables/{table}` |\n| Delete table | DELETE | `/v1/namespaces/{ns}/tables/{table}` |\n| Rename table | POST | `/v1/tables/rename` |\n\n**Authentication:** Bearer token in header: `Authorization: Bearer `\n\n## PyIceberg Client API\n\nMost users use PyIceberg, not raw REST.\n\n### Connection\n\n```python\nfrom pyiceberg.catalog.rest import RestCatalog\n\ncatalog = RestCatalog(\n name=\"my_catalog\",\n warehouse=\"\",\n uri=\"\",\n token=\"\",\n)\n```\n\n### Namespace Operations\n\n```python\nfrom pyiceberg.exceptions import NamespaceAlreadyExistsError\n\nnamespaces = catalog.list_namespaces() # [('default',), ('logs',)]\ncatalog.create_namespace(\"logs\", properties={\"owner\": \"team\"})\ncatalog.drop_namespace(\"logs\") # Must be empty\n```\n\n### Table Operations\n\n```python\nfrom pyiceberg.schema import Schema\nfrom pyiceberg.types import NestedField, StringType, IntegerType\n\nschema = Schema(\n NestedField(1, \"id\", IntegerType(), required=True),\n NestedField(2, \"name\", StringType(), required=False),\n)\ntable = catalog.create_table((\"logs\", \"app_logs\"), schema=schema)\ntables = catalog.list_tables(\"logs\")\ntable = catalog.load_table((\"logs\", \"app_logs\"))\ncatalog.rename_table((\"logs\", \"old\"), (\"logs\", \"new\"))\n```\n\n### Data Operations\n\n```python\nimport pyarrow as pa\n\ndata = pa.table({\"id\": [1, 2], \"name\": [\"Alice\", \"Bob\"]})\ntable.append(data)\ntable.overwrite(data)\n\n# Read with filters\nscan = table.scan(row_filter=\"id > 100\", selected_fields=[\"id\", \"name\"])\ndf = scan.to_pandas()\n```\n\n### Schema Evolution\n\n```python\nfrom pyiceberg.types import IntegerType, LongType\n\nwith table.update_schema() as update:\n update.add_column(\"user_id\", IntegerType(), doc=\"User ID\")\n update.rename_column(\"msg\", \"message\")\n update.delete_column(\"old_field\")\n update.update_column(\"id\", field_type=LongType()) # int→long only\n```\n\n### Time-Travel\n\n```python\nfrom datetime import datetime, timedelta\n\n# Query specific snapshot or timestamp\nscan = table.scan(snapshot_id=table.snapshots()[-2].snapshot_id)\nyesterday_ms = int((datetime.now() - timedelta(days=1)).timestamp() * 1000)\nscan = table.scan(as_of_timestamp=yesterday_ms)\n```\n\n### Partitioning\n\n```python\nfrom pyiceberg.partitioning import PartitionSpec, PartitionField\nfrom pyiceberg.transforms import DayTransform\nfrom pyiceberg.types import TimestampType\n\npartition_spec = PartitionSpec(\n PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name=\"day\")\n)\ntable = catalog.create_table((\"events\", \"actions\"), schema=schema, partition_spec=partition_spec)\nscan = table.scan(row_filter=\"day = '2026-01-27'\") # Prunes partitions\n```\n\n## Table Maintenance\n\n### Compaction\n\n```python\nfiles = table.scan().plan_files()\navg_mb = sum(f.file_size_in_bytes for f in files) / len(files) / (1024**2)\nprint(f\"Files: {len(files)}, Avg: {avg_mb:.1f} MB\")\n\ntable.rewrite_data_files(target_file_size_bytes=128 * 1024 * 1024)\n```\n\n**When:** Avg <10MB or >1000 files. **Frequency:** High-write daily, medium weekly.\n\n### Snapshot Expiration\n\n```python\nfrom datetime import datetime, timedelta\n\nseven_days_ms = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)\ntable.expire_snapshots(older_than=seven_days_ms, retain_last=10)\n```\n\n**Retention:** Production 7-30d, dev 1-7d, audit 90+d.\n\n### Orphan Cleanup\n\n```python\nthree_days_ms = int((datetime.now() - timedelta(days=3)).timestamp() * 1000)\ntable.delete_orphan_files(older_than=three_days_ms)\n```\n\n⚠️ Always expire snapshots first, use 3+ day threshold, run during low traffic.\n\n### Full Maintenance\n\n```python\n# Compact → Expire → Cleanup (in order)\nif len(table.scan().plan_files()) > 1000:\n table.rewrite_data_files(target_file_size_bytes=128 * 1024 * 1024)\nseven_days_ms = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)\ntable.expire_snapshots(older_than=seven_days_ms, retain_last=10)\nthree_days_ms = int((datetime.now() - timedelta(days=3)).timestamp() * 1000)\ntable.delete_orphan_files(older_than=three_days_ms)\n```\n\n## Metadata Inspection\n\n```python\ntable = catalog.load_table((\"logs\", \"app_logs\"))\nprint(table.schema())\nprint(table.current_snapshot())\nprint(table.properties)\nprint(f\"Files: {len(table.scan().plan_files())}\")\n```\n\n## Error Codes\n\n| Code | Meaning | Common Causes |\n|------|---------|---------------|\n| 401 | Unauthorized | Invalid/missing token |\n| 404 | Not Found | Catalog not enabled, namespace/table missing |\n| 409 | Conflict | Already exists, concurrent update |\n| 422 | Validation | Invalid schema, incompatible type |\n\nSee [gotchas.md](gotchas.md) for detailed troubleshooting.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-data-catalog/configuration.md", "content": "# Configuration\n\nHow to enable R2 Data Catalog and configure authentication.\n\n## Prerequisites\n\n- Cloudflare account with [R2 subscription](https://developers.cloudflare.com/r2/pricing/)\n- R2 bucket created\n- Access to Cloudflare dashboard or Wrangler CLI\n\n## Enable Catalog on Bucket\n\nChoose one method:\n\n### Via Wrangler (Recommended)\n\n```bash\nnpx wrangler r2 bucket catalog enable \n```\n\n**Output:**\n```\n✅ Data Catalog enabled for bucket 'my-bucket'\n Catalog URI: https://.r2.cloudflarestorage.com/iceberg/my-bucket\n Warehouse: my-bucket\n```\n\n### Via Dashboard\n\n1. Navigate to **R2** → Select your bucket → **Settings** tab\n2. Scroll to \"R2 Data Catalog\" section → Click **Enable**\n3. Note the **Catalog URI** and **Warehouse name** shown\n\n**Result:**\n- Catalog URI: `https://.r2.cloudflarestorage.com/iceberg/`\n- Warehouse: `` (same as bucket name)\n\n### Via API (Programmatic)\n\n```bash\ncurl -X POST \\\n \"https://api.cloudflare.com/client/v4/accounts//r2/buckets//catalog\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\"\n```\n\n**Response:**\n```json\n{\n \"result\": {\n \"catalog_uri\": \"https://.r2.cloudflarestorage.com/iceberg/\",\n \"warehouse\": \"\"\n },\n \"success\": true\n}\n```\n\n## Check Catalog Status\n\n```bash\nnpx wrangler r2 bucket catalog status \n```\n\n**Output:**\n```\nCatalog Status: enabled\nCatalog URI: https://.r2.cloudflarestorage.com/iceberg/my-bucket\nWarehouse: my-bucket\n```\n\n## Disable Catalog (If Needed)\n\n```bash\nnpx wrangler r2 bucket catalog disable \n```\n\n⚠️ **Warning:** Disabling does NOT delete tables/data. Files remain in bucket. Metadata becomes inaccessible until re-enabled.\n\n## API Token Creation\n\nR2 Data Catalog requires API token with **both** R2 Storage + R2 Data Catalog permissions.\n\n### Dashboard Method (Recommended)\n\n1. Go to **R2** → **Manage R2 API Tokens** → **Create API Token**\n2. Select permission level:\n - **Admin Read & Write** - Full catalog + storage access (read/write)\n - **Admin Read only** - Read-only access (for query engines)\n3. Copy token value immediately (shown only once)\n\n**Permission groups included:**\n- `Workers R2 Data Catalog Write` (or Read)\n- `Workers R2 Storage Bucket Item Write` (or Read)\n\n### API Method (Programmatic)\n\nUse Cloudflare API to create tokens programmatically. Required permissions:\n- `Workers R2 Data Catalog Write` (or Read)\n- `Workers R2 Storage Bucket Item Write` (or Read)\n\n## Client Configuration\n\n### PyIceberg\n\n```python\nfrom pyiceberg.catalog.rest import RestCatalog\n\ncatalog = RestCatalog(\n name=\"my_catalog\",\n warehouse=\"\", # Same as bucket name\n uri=\"\", # From enable command\n token=\"\", # From token creation\n)\n```\n\n**Full example with credentials:**\n```python\nimport os\nfrom pyiceberg.catalog.rest import RestCatalog\n\n# Store credentials in environment variables\nWAREHOUSE = os.getenv(\"R2_WAREHOUSE\") # e.g., \"my-bucket\"\nCATALOG_URI = os.getenv(\"R2_CATALOG_URI\") # e.g., \"https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket\"\nTOKEN = os.getenv(\"R2_TOKEN\") # API token\n\ncatalog = RestCatalog(\n name=\"r2_catalog\",\n warehouse=WAREHOUSE,\n uri=CATALOG_URI,\n token=TOKEN,\n)\n\n# Test connection\nprint(catalog.list_namespaces())\n```\n\n### Spark / Trino / DuckDB\n\nSee [patterns.md](patterns.md) for integration examples with other query engines.\n\n## Connection String Format\n\nFor quick reference:\n\n```\nCatalog URI: https://.r2.cloudflarestorage.com/iceberg/\nWarehouse: \nToken: \n```\n\n**Where to find values:**\n\n| Value | Source |\n|-------|--------|\n| `` | Dashboard URL or `wrangler whoami` |\n| `` | R2 bucket name |\n| Catalog URI | Output from `wrangler r2 bucket catalog enable` |\n| Token | R2 API Token creation page |\n\n## Security Best Practices\n\n1. **Store tokens securely** - Use environment variables or secret managers, never hardcode\n2. **Use least privilege** - Read-only tokens for query engines, write tokens only where needed\n3. **Rotate tokens regularly** - Create new tokens, test, then revoke old ones\n4. **One token per application** - Easier to track and revoke if compromised\n5. **Monitor token usage** - Check R2 analytics for unexpected patterns\n6. **Bucket-scoped tokens** - Create tokens per bucket, not account-wide\n\n## Environment Variables Pattern\n\n```bash\n# .env (never commit)\nR2_CATALOG_URI=https://.r2.cloudflarestorage.com/iceberg/\nR2_WAREHOUSE=\nR2_TOKEN=\n```\n\n```python\nimport os\nfrom pyiceberg.catalog.rest import RestCatalog\n\ncatalog = RestCatalog(\n name=\"r2\",\n uri=os.getenv(\"R2_CATALOG_URI\"),\n warehouse=os.getenv(\"R2_WAREHOUSE\"),\n token=os.getenv(\"R2_TOKEN\"),\n)\n```\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| 404 \"catalog not found\" | Run `wrangler r2 bucket catalog enable ` |\n| 401 \"unauthorized\" | Check token has both Catalog + Storage permissions |\n| 403 on data files | Token needs both permission groups |\n\nSee [gotchas.md](gotchas.md) for detailed troubleshooting.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-data-catalog/gotchas.md", "content": "# Gotchas & Troubleshooting\n\nCommon problems → causes → solutions.\n\n## Permission Errors\n\n### 401 Unauthorized\n\n**Error:** `\"401 Unauthorized\"` \n**Cause:** Token missing R2 Data Catalog permissions. \n**Solution:** Use \"Admin Read & Write\" token (includes catalog + storage permissions). Test with `catalog.list_namespaces()`.\n\n### 403 Forbidden\n\n**Error:** `\"403 Forbidden\"` on data files \n**Cause:** Token lacks storage permissions. \n**Solution:** Token needs both R2 Data Catalog + R2 Storage Bucket Item permissions.\n\n### Token Rotation Issues\n\n**Error:** New token fails after rotation. \n**Solution:** Create new token → test in staging → update prod → monitor 24h → revoke old.\n\n## Catalog URI Issues\n\n### 404 Not Found\n\n**Error:** `\"404 Catalog not found\"` \n**Cause:** Catalog not enabled or wrong URI. \n**Solution:** Run `wrangler r2 bucket catalog enable `. URI must be HTTPS with `/iceberg/` and case-sensitive bucket name.\n\n### Wrong Warehouse\n\n**Error:** Cannot create/load tables. \n**Cause:** Warehouse ≠ bucket name. \n**Solution:** Set `warehouse=\"bucket-name\"` to match bucket exactly.\n\n## Table and Schema Issues\n\n### Table/Namespace Already Exists\n\n**Error:** `\"TableAlreadyExistsError\"` \n**Solution:** Use try/except to load existing or check first.\n\n### Namespace Not Found\n\n**Error:** Cannot create table. \n**Solution:** Create namespace first: `catalog.create_namespace(\"ns\")`\n\n### Schema Evolution Errors\n\n**Error:** `\"422 Validation\"` on schema update. \n**Cause:** Incompatible change (required field, type shrink). \n**Solution:** Only add nullable columns, compatible type widening (int→long, float→double).\n\n## Data and Query Issues\n\n### Empty Scan Results\n\n**Error:** Scan returns no data. \n**Cause:** Incorrect filter or partition column. \n**Solution:** Test without filter first: `table.scan().to_pandas()`. Verify partition column names.\n\n### Slow Queries\n\n**Error:** Performance degrades over time. \n**Cause:** Too many small files. \n**Solution:** Check file count, compact if >1000 or avg <10MB. See [api.md](api.md#compaction).\n\n### Type Mismatch\n\n**Error:** `\"Cannot cast\"` on append. \n**Cause:** PyArrow types don't match Iceberg schema. \n**Solution:** Cast to int64 (Iceberg default), not int32. Check `table.schema()`.\n\n## Compaction Issues\n\n### Compaction Issues\n\n**Problem:** File count unchanged or compaction takes hours. \n**Cause:** Target size too large, or table too big for PyIceberg. \n**Solution:** Only compact if avg <50MB. For >1TB tables, use Spark. Run during low-traffic periods.\n\n## Maintenance Issues\n\n### Snapshot/Orphan Issues\n\n**Problem:** Expiration fails or orphan cleanup deletes active data. \n**Cause:** Too aggressive retention or wrong order. \n**Solution:** Always expire snapshots first with `retain_last=10`, then cleanup orphans with 3+ day threshold.\n\n## Concurrency Issues\n\n### Concurrent Write Conflicts\n\n**Problem:** `CommitFailedException` with multiple writers. \n**Cause:** Optimistic locking - simultaneous commits. \n**Solution:** Add retry with exponential backoff (see [patterns.md](patterns.md#pattern-6-concurrent-writes-with-retry)).\n\n### Stale Metadata\n\n**Problem:** Old schema/data after external update. \n**Cause:** Cached metadata. \n**Solution:** Reload table: `table = catalog.load_table((\"ns\", \"table\"))`\n\n## Performance Optimization\n\n### Performance Tips\n\n**Scans:** Use `row_filter` and `selected_fields` to reduce data scanned. \n**Partitions:** 100-1000 optimal. Avoid high cardinality (millions) or low (<10). \n**Files:** Keep 100-500MB avg. Compact if <10MB or >10k files.\n\n## Limits\n\n| Resource | Recommended | Impact if Exceeded |\n|----------|-------------|-------------------|\n| Tables/namespace | <10k | Slow list ops |\n| Files/table | <100k | Slow query planning |\n| Partitions/table | 100-1k | Metadata overhead |\n| Snapshots/table | Expire >7d | Metadata bloat |\n\n## Common Error Messages Reference\n\n| Error Message | Likely Cause | Fix |\n|---------------|--------------|-----|\n| `401 Unauthorized` | Missing/invalid token | Check token has catalog+storage permissions |\n| `403 Forbidden` | Token lacks storage permissions | Add R2 Storage Bucket Item permission |\n| `404 Not Found` | Catalog not enabled or wrong URI | Run `wrangler r2 bucket catalog enable` |\n| `409 Conflict` | Table/namespace already exists | Use try/except or load existing |\n| `422 Unprocessable Entity` | Schema validation failed | Check type compatibility, required fields |\n| `CommitFailedException` | Concurrent write conflict | Add retry logic with backoff |\n| `NamespaceAlreadyExistsError` | Namespace exists | Use try/except or load existing |\n| `NoSuchTableError` | Table doesn't exist | Check namespace+table name, create first |\n| `TypeError: Cannot cast` | PyArrow type mismatch | Cast data to match Iceberg schema |\n\n## Debugging Checklist\n\nWhen things go wrong, check in order:\n\n1. ✅ **Catalog enabled:** `npx wrangler r2 bucket catalog status `\n2. ✅ **Token permissions:** Both R2 Data Catalog + R2 Storage in dashboard\n3. ✅ **Connection test:** `catalog.list_namespaces()` succeeds\n4. ✅ **URI format:** HTTPS, includes `/iceberg/`, correct bucket name\n5. ✅ **Warehouse name:** Matches bucket name exactly\n6. ✅ **Namespace exists:** Create before `create_table()`\n7. ✅ **Enable debug logging:** `logging.basicConfig(level=logging.DEBUG)`\n8. ✅ **PyIceberg version:** `pip install --upgrade pyiceberg` (≥0.5.0)\n9. ✅ **File health:** Compact if >1000 files or avg <10MB\n10. ✅ **Snapshot count:** Expire if >100 snapshots\n\n## Enable Debug Logging\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n# Now operations show HTTP requests/responses\n```\n\n## Resources\n\n- [Cloudflare Community](https://community.cloudflare.com/c/developers/workers/40)\n- [Cloudflare Discord](https://discord.cloudflare.com) - #r2 channel\n- [PyIceberg GitHub](https://github.com/apache/iceberg-python/issues)\n- [Apache Iceberg Slack](https://iceberg.apache.org/community/)\n\n## Next Steps\n\n- [patterns.md](patterns.md) - Working examples\n- [api.md](api.md) - API reference\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-data-catalog/patterns.md", "content": "# Common Patterns\n\nPractical patterns for R2 Data Catalog with PyIceberg.\n\n## PyIceberg Connection\n\n```python\nimport os\nfrom pyiceberg.catalog.rest import RestCatalog\nfrom pyiceberg.exceptions import NamespaceAlreadyExistsError\n\ncatalog = RestCatalog(\n name=\"r2_catalog\",\n warehouse=os.getenv(\"R2_WAREHOUSE\"), # bucket name\n uri=os.getenv(\"R2_CATALOG_URI\"), # catalog endpoint\n token=os.getenv(\"R2_TOKEN\"), # API token\n)\n\n# Create namespace (idempotent)\ntry:\n catalog.create_namespace(\"default\")\nexcept NamespaceAlreadyExistsError:\n pass\n```\n\n## Pattern 1: Log Analytics Pipeline\n\nIngest logs incrementally, query by time/level.\n\n```python\nimport pyarrow as pa\nfrom datetime import datetime\nfrom pyiceberg.schema import Schema\nfrom pyiceberg.types import NestedField, TimestampType, StringType, IntegerType\nfrom pyiceberg.partitioning import PartitionSpec, PartitionField\nfrom pyiceberg.transforms import DayTransform\n\n# Create partitioned table (once)\nschema = Schema(\n NestedField(1, \"timestamp\", TimestampType(), required=True),\n NestedField(2, \"level\", StringType(), required=True),\n NestedField(3, \"service\", StringType(), required=True),\n NestedField(4, \"message\", StringType(), required=False),\n)\n\npartition_spec = PartitionSpec(\n PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name=\"day\")\n)\n\ncatalog.create_namespace(\"logs\")\ntable = catalog.create_table((\"logs\", \"app_logs\"), schema=schema, partition_spec=partition_spec)\n\n# Append logs (incremental)\ndata = pa.table({\n \"timestamp\": [datetime(2026, 1, 27, 10, 30, 0)],\n \"level\": [\"ERROR\"],\n \"service\": [\"auth-service\"],\n \"message\": [\"Failed login\"],\n})\ntable.append(data)\n\n# Query by time + level (leverages partitioning)\nscan = table.scan(row_filter=\"level = 'ERROR' AND day = '2026-01-27'\")\nerrors = scan.to_pandas()\n```\n\n## Pattern 2: Time-Travel Queries\n\n```python\nfrom datetime import datetime, timedelta\n\ntable = catalog.load_table((\"logs\", \"app_logs\"))\n\n# Query specific snapshot\nsnapshot_id = table.current_snapshot().snapshot_id\ndata = table.scan(snapshot_id=snapshot_id).to_pandas()\n\n# Query as of timestamp (yesterday)\nyesterday_ms = int((datetime.now() - timedelta(days=1)).timestamp() * 1000)\ndata = table.scan(as_of_timestamp=yesterday_ms).to_pandas()\n```\n\n## Pattern 3: Schema Evolution\n\n```python\nfrom pyiceberg.types import StringType\n\ntable = catalog.load_table((\"users\", \"profiles\"))\n\nwith table.update_schema() as update:\n update.add_column(\"email\", StringType(), required=False)\n update.rename_column(\"name\", \"full_name\")\n# Old readers ignore new columns, new readers see nulls for old data\n```\n\n## Pattern 4: Partitioned Tables\n\n```python\nfrom pyiceberg.partitioning import PartitionSpec, PartitionField\nfrom pyiceberg.transforms import DayTransform, IdentityTransform\n\n# Partition by day + country\npartition_spec = PartitionSpec(\n PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name=\"day\"),\n PartitionField(source_id=2, field_id=1001, transform=IdentityTransform(), name=\"country\"),\n)\ntable = catalog.create_table((\"events\", \"user_events\"), schema=schema, partition_spec=partition_spec)\n\n# Queries prune partitions automatically\nscan = table.scan(row_filter=\"country = 'US' AND day = '2026-01-27'\")\n```\n\n## Pattern 5: Table Maintenance\n\n```python\nfrom datetime import datetime, timedelta\n\ntable = catalog.load_table((\"logs\", \"app_logs\"))\n\n# Compact → expire → cleanup (in order)\ntable.rewrite_data_files(target_file_size_bytes=128 * 1024 * 1024)\nseven_days_ms = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)\ntable.expire_snapshots(older_than=seven_days_ms, retain_last=10)\nthree_days_ms = int((datetime.now() - timedelta(days=3)).timestamp() * 1000)\ntable.delete_orphan_files(older_than=three_days_ms)\n```\n\nSee [api.md](api.md#table-maintenance) for detailed parameters.\n\n## Pattern 6: Concurrent Writes with Retry\n\n```python\nfrom pyiceberg.exceptions import CommitFailedException\nimport time\n\ndef append_with_retry(table, data, max_retries=3):\n for attempt in range(max_retries):\n try:\n table.append(data)\n return\n except CommitFailedException:\n if attempt == max_retries - 1:\n raise\n time.sleep(2 ** attempt)\n```\n\n## Pattern 7: Upsert Simulation\n\n```python\nimport pandas as pd\nimport pyarrow as pa\n\n# Read → merge → overwrite (not atomic, use Spark MERGE INTO for production)\nexisting = table.scan().to_pandas()\nnew_data = pd.DataFrame({\"id\": [1, 3], \"value\": [100, 300]})\nmerged = pd.concat([existing, new_data]).drop_duplicates(subset=[\"id\"], keep=\"last\")\ntable.overwrite(pa.Table.from_pandas(merged))\n```\n\n## Pattern 8: DuckDB Integration\n\n```python\nimport duckdb\n\narrow_table = table.scan().to_arrow()\ncon = duckdb.connect()\ncon.register(\"logs\", arrow_table)\nresult = con.execute(\"SELECT level, COUNT(*) FROM logs GROUP BY level\").fetchdf()\n```\n\n## Pattern 9: Monitor Table Health\n\n```python\nfiles = table.scan().plan_files()\navg_mb = sum(f.file_size_in_bytes for f in files) / len(files) / (1024**2)\nprint(f\"Files: {len(files)}, Avg: {avg_mb:.1f}MB, Snapshots: {len(table.snapshots())}\")\n\nif avg_mb < 10 or len(files) > 1000:\n print(\"⚠️ Needs compaction\")\n```\n\n## Best Practices\n\n| Area | Guideline |\n|------|-----------|\n| **Partitioning** | Use day/hour for time-series; 100-1000 partitions; avoid high cardinality |\n| **File sizes** | Target 128-512MB; compact when avg <10MB or >10k files |\n| **Schema** | Add columns as nullable (`required=False`); batch changes |\n| **Maintenance** | Compact high-write daily/weekly; expire snapshots 7-30d; cleanup orphans after |\n| **Concurrency** | Reads automatic; writes to different partitions safe; retry same partition |\n| **Performance** | Filter on partitions; select only needed columns; batch appends 100MB+ |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-sql/README.md", "content": "# Cloudflare R2 SQL Skill Reference\n\nExpert guidance for Cloudflare R2 SQL - serverless distributed query engine for Apache Iceberg tables.\n\n## Reading Order\n\n**New to R2 SQL?** Start here:\n1. Read \"What is R2 SQL?\" and \"When to Use\" below\n2. [configuration.md](configuration.md) - Enable catalog, create tokens\n3. [patterns.md](patterns.md) - Wrangler CLI and integration examples\n4. [api.md](api.md) - SQL syntax and query reference\n5. [gotchas.md](gotchas.md) - Limitations and troubleshooting\n\n**Quick reference?** Jump to:\n- [Run a query via Wrangler](patterns.md#wrangler-cli-query)\n- [SQL syntax reference](api.md#sql-syntax)\n- [ORDER BY limitations](gotchas.md#order-by-limitations)\n\n## What is R2 SQL?\n\nR2 SQL is Cloudflare's **serverless distributed analytics query engine** for querying Apache Iceberg tables in R2 Data Catalog. Features:\n\n- **Serverless** - No clusters to manage, no infrastructure\n- **Distributed** - Leverages Cloudflare's global network for parallel execution\n- **SQL interface** - Familiar SQL syntax for analytics queries\n- **Zero egress fees** - Query from any cloud/region without data transfer costs\n- **Open beta** - Free during beta (standard R2 storage costs apply)\n\n### What is Apache Iceberg?\n\nOpen table format for large-scale analytics datasets in object storage:\n- **ACID transactions** - Safe concurrent reads/writes\n- **Metadata optimization** - Fast queries without full table scans\n- **Schema evolution** - Add/rename/drop columns without rewrites\n- **Partitioning** - Organize data for efficient pruning\n\n## When to Use\n\n**Use R2 SQL for:**\n- **Log analytics** - Query application/system logs with WHERE filters and aggregations\n- **BI dashboards** - Generate reports from large analytical datasets\n- **Fraud detection** - Analyze transaction patterns with GROUP BY/HAVING\n- **Multi-cloud analytics** - Query data from any cloud without egress fees\n- **Ad-hoc exploration** - Run SQL queries on Iceberg tables via Wrangler CLI\n\n**Don't use R2 SQL for:**\n- **Workers/Pages runtime** - R2 SQL has no Workers binding, use HTTP API from external systems\n- **Real-time queries (<100ms)** - Optimized for analytical batch queries, not OLTP\n- **Complex joins/CTEs** - Limited SQL feature set (no JOINs, subqueries, CTEs currently)\n- **Small datasets (<1GB)** - Setup overhead not justified\n\n## Decision Tree: Need to Query R2 Data?\n\n```\nDo you need to query structured data in R2?\n├─ YES, data is in Iceberg tables\n│ ├─ Need SQL interface? → Use R2 SQL (this reference)\n│ ├─ Need Python API? → See r2-data-catalog reference (PyIceberg)\n│ └─ Need other engine? → See r2-data-catalog reference (Spark, Trino, etc.)\n│\n├─ YES, but not in Iceberg format\n│ ├─ Streaming data? → Use Pipelines to write to Data Catalog, then R2 SQL\n│ └─ Static files? → Use PyIceberg to create Iceberg tables, then R2 SQL\n│\n└─ NO, just need object storage → Use R2 reference (not R2 SQL)\n```\n\n## Architecture Overview\n\n**Query Planner:**\n- Top-down metadata investigation with multi-layer pruning\n- Partition-level, column-level, and row-group pruning\n- Streaming pipeline - execution starts before planning completes\n- Early termination with LIMIT - stops when result complete\n\n**Query Execution:**\n- Coordinator distributes work to workers across Cloudflare network\n- Workers run Apache DataFusion for parallel query execution\n- Parquet column pruning - reads only required columns\n- Ranged reads from R2 for efficiency\n\n**Aggregation Strategies:**\n- Scatter-gather - simple aggregations (SUM, COUNT, AVG)\n- Shuffling - ORDER BY/HAVING on aggregates via hash partitioning\n\n## Quick Start\n\n```bash\n# 1. Enable R2 Data Catalog on bucket\nnpx wrangler r2 bucket catalog enable my-bucket\n\n# 2. Create API token (Admin Read & Write)\n# Dashboard: R2 → Manage API tokens → Create API token\n\n# 3. Set environment variable\nexport WRANGLER_R2_SQL_AUTH_TOKEN=\n\n# 4. Run query\nnpx wrangler r2 sql query \"my-bucket\" \"SELECT * FROM default.my_table LIMIT 10\"\n```\n\n## Important Limitations\n\n**CRITICAL: No Workers Binding**\n- R2 SQL cannot be called directly from Workers/Pages code\n- For programmatic access, use HTTP API from external systems\n- Or query via PyIceberg, Spark, etc. (see r2-data-catalog reference)\n\n**SQL Feature Set:**\n- No JOINs, CTEs, subqueries, window functions\n- ORDER BY supports aggregation columns (not just partition keys)\n- LIMIT max 10,000 (default 500)\n- See [gotchas.md](gotchas.md) for complete limitations\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Enable catalog, create API tokens\n- **[api.md](api.md)** - SQL syntax, functions, operators, data types\n- **[patterns.md](patterns.md)** - Wrangler CLI, HTTP API, Pipelines, PyIceberg\n- **[gotchas.md](gotchas.md)** - Limitations, troubleshooting, performance tips\n\n## See Also\n\n- [r2-data-catalog](../r2-data-catalog/) - PyIceberg, REST API, external engines\n- [pipelines](../pipelines/) - Streaming ingestion to Iceberg tables\n- [r2](../r2/) - R2 object storage fundamentals\n- [Cloudflare R2 SQL Docs](https://developers.cloudflare.com/r2-sql/)\n- [R2 SQL Deep Dive Blog](https://blog.cloudflare.com/r2-sql-deep-dive/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-sql/api.md", "content": "# R2 SQL API Reference\n\nSQL syntax, functions, operators, and data types for R2 SQL queries.\n\n## SQL Syntax\n\n```sql\nSELECT column_list | aggregation_function\nFROM [namespace.]table_name\nWHERE conditions\n[GROUP BY column_list]\n[HAVING conditions]\n[ORDER BY column | aggregation_function [DESC | ASC]]\n[LIMIT number]\n```\n\n## Schema Discovery\n\n```sql\nSHOW DATABASES; -- List namespaces\nSHOW NAMESPACES; -- Alias for SHOW DATABASES\nSHOW SCHEMAS; -- Alias for SHOW DATABASES\nSHOW TABLES IN namespace; -- List tables in namespace\nDESCRIBE namespace.table; -- Show table schema, partition keys\n```\n\n## SELECT Clause\n\n```sql\n-- All columns\nSELECT * FROM logs.http_requests;\n\n-- Specific columns\nSELECT user_id, timestamp, status FROM logs.http_requests;\n```\n\n**Limitations:** No column aliases, expressions, or nested column access\n\n## WHERE Clause\n\n### Operators\n\n| Operator | Example |\n|----------|---------|\n| `=`, `!=`, `<`, `<=`, `>`, `>=` | `status = 200` |\n| `LIKE` | `user_agent LIKE '%Chrome%'` |\n| `BETWEEN` | `timestamp BETWEEN '2025-01-01T00:00:00Z' AND '2025-01-31T23:59:59Z'` |\n| `IS NULL`, `IS NOT NULL` | `email IS NOT NULL` |\n| `AND`, `OR` | `status = 200 AND method = 'GET'` |\n\nUse parentheses for precedence: `(status = 404 OR status = 500) AND method = 'POST'`\n\n## Aggregation Functions\n\n| Function | Description |\n|----------|-------------|\n| `COUNT(*)` | Count all rows |\n| `COUNT(column)` | Count non-null values |\n| `COUNT(DISTINCT column)` | Count unique values |\n| `SUM(column)`, `AVG(column)` | Numeric aggregations |\n| `MIN(column)`, `MAX(column)` | Min/max values |\n\n```sql\n-- Multiple aggregations with GROUP BY\nSELECT region, COUNT(*), SUM(amount), AVG(amount)\nFROM sales.transactions\nWHERE sale_date >= '2024-01-01'\nGROUP BY region;\n```\n\n## HAVING Clause\n\nFilter aggregated results (after GROUP BY):\n\n```sql\nSELECT category, SUM(amount)\nFROM sales.transactions\nGROUP BY category\nHAVING SUM(amount) > 10000;\n```\n\n## ORDER BY Clause\n\nSort results by:\n- **Partition key columns** - Always supported\n- **Aggregation functions** - Supported via shuffle strategy\n\n```sql\n-- Order by partition key\nSELECT * FROM logs.requests ORDER BY timestamp DESC LIMIT 100;\n\n-- Order by aggregation (repeat function, aliases not supported)\nSELECT region, SUM(amount)\nFROM sales.transactions\nGROUP BY region\nORDER BY SUM(amount) DESC;\n```\n\n**Limitations:** Cannot order by non-partition columns. See [gotchas.md](gotchas.md#order-by-limitations)\n\n## LIMIT Clause\n\n```sql\nSELECT * FROM logs.requests LIMIT 100;\n```\n\n| Setting | Value |\n|---------|-------|\n| Min | 1 |\n| Max | 10,000 |\n| Default | 500 |\n\n**Always use LIMIT** to enable early termination optimization.\n\n## Data Types\n\n| Type | SQL Literal | Example |\n|------|-------------|---------|\n| `integer` | Unquoted number | `42`, `-10` |\n| `float` | Decimal number | `3.14`, `-0.5` |\n| `string` | Single quotes | `'hello'`, `'GET'` |\n| `boolean` | Keyword | `true`, `false` |\n| `timestamp` | RFC3339 string | `'2025-01-01T00:00:00Z'` |\n| `date` | ISO 8601 date | `'2025-01-01'` |\n\n### Type Safety\n\n- Quote strings with single quotes: `'value'`\n- Timestamps must be RFC3339: `'2025-01-01T00:00:00Z'` (include timezone)\n- Dates must be ISO 8601: `'2025-01-01'` (YYYY-MM-DD)\n- No implicit conversions\n\n```sql\n-- ✅ Correct\nWHERE status = 200 AND method = 'GET' AND timestamp > '2025-01-01T00:00:00Z'\n\n-- ❌ Wrong\nWHERE status = '200' -- string instead of integer\nWHERE timestamp > '2025-01-01' -- missing time/timezone\nWHERE method = GET -- unquoted string\n```\n\n## Query Result Format\n\nJSON array of objects:\n\n```json\n[\n {\"user_id\": \"user_123\", \"timestamp\": \"2025-01-15T10:30:00Z\", \"status\": 200},\n {\"user_id\": \"user_456\", \"timestamp\": \"2025-01-15T10:31:00Z\", \"status\": 404}\n]\n```\n\n## See Also\n\n- [patterns.md](patterns.md) - Query examples and use cases\n- [gotchas.md](gotchas.md) - SQL limitations and error handling\n- [configuration.md](configuration.md) - Setup and authentication\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-sql/configuration.md", "content": "# R2 SQL Configuration\n\nSetup and configuration for R2 SQL queries.\n\n## Prerequisites\n\n- R2 bucket with Data Catalog enabled\n- API token with R2 permissions\n- Wrangler CLI installed (for CLI queries)\n\n## Enable R2 Data Catalog\n\nR2 SQL queries Apache Iceberg tables in R2 Data Catalog. Must enable catalog on bucket first.\n\n### Via Wrangler CLI\n\n```bash\nnpx wrangler r2 bucket catalog enable \n```\n\nOutput includes:\n- **Warehouse name** - Typically same as bucket name\n- **Catalog URI** - REST endpoint for catalog operations\n\nExample output:\n```\nCatalog enabled successfully\nWarehouse: my-bucket\nCatalog URI: https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket\n```\n\n### Via Dashboard\n\n1. Navigate to **R2 Object Storage** → Select your bucket\n2. Click **Settings** tab\n3. Scroll to **R2 Data Catalog** section\n4. Click **Enable**\n5. Note the **Catalog URI** and **Warehouse** name\n\n**Important:** Enabling catalog creates metadata directories in bucket but does not modify existing objects.\n\n## Create API Token\n\nR2 SQL requires API token with R2 permissions.\n\n### Required Permission\n\n**R2 Admin Read & Write** (includes R2 SQL Read permission)\n\n### Via Dashboard\n\n1. Navigate to **R2 Object Storage**\n2. Click **Manage API tokens** (top right)\n3. Click **Create API token**\n4. Select **Admin Read & Write** permission\n5. Click **Create API Token**\n6. **Copy token value** - shown only once\n\n### Permission Scope\n\n| Permission | Grants Access To |\n|------------|------------------|\n| R2 Admin Read & Write | R2 storage operations + R2 SQL queries + Data Catalog operations |\n| R2 SQL Read | SQL queries only (no storage writes) |\n\n**Note:** R2 SQL Read permission not yet available via Dashboard - use Admin Read & Write.\n\n## Configure Environment\n\n### Wrangler CLI\n\nSet environment variable for Wrangler to use:\n\n```bash\nexport WRANGLER_R2_SQL_AUTH_TOKEN=\n```\n\nOr create `.env` file in project directory:\n\n```\nWRANGLER_R2_SQL_AUTH_TOKEN=\n```\n\nWrangler automatically loads `.env` file when running commands.\n\n### HTTP API\n\nFor programmatic access (non-Wrangler), pass token in Authorization header:\n\n```bash\ncurl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"warehouse\": \"my-bucket\",\n \"query\": \"SELECT * FROM default.my_table LIMIT 10\"\n }'\n```\n\n**Note:** HTTP API endpoint URL may vary - see [patterns.md](patterns.md#http-api-query) for current endpoint.\n\n## Verify Setup\n\nTest configuration by querying system tables:\n\n```bash\n# List namespaces\nnpx wrangler r2 sql query \"my-bucket\" \"SHOW DATABASES\"\n\n# List tables in namespace\nnpx wrangler r2 sql query \"my-bucket\" \"SHOW TABLES IN default\"\n```\n\nIf successful, returns JSON array of results.\n\n## Troubleshooting\n\n### \"Token authentication failed\"\n\n**Cause:** Invalid or missing token\n\n**Solution:**\n- Verify `WRANGLER_R2_SQL_AUTH_TOKEN` environment variable set\n- Check token has Admin Read & Write permission\n- Create new token if expired\n\n### \"Catalog not enabled on bucket\"\n\n**Cause:** Data Catalog not enabled\n\n**Solution:**\n- Run `npx wrangler r2 bucket catalog enable `\n- Or enable via Dashboard (R2 → bucket → Settings → R2 Data Catalog)\n\n### \"Permission denied\"\n\n**Cause:** Token lacks required permissions\n\n**Solution:**\n- Verify token has **Admin Read & Write** permission\n- Create new token with correct permissions\n\n## See Also\n\n- [r2-data-catalog/configuration.md](../r2-data-catalog/configuration.md) - Detailed token setup and PyIceberg connection\n- [patterns.md](patterns.md) - Query examples using configuration\n- [gotchas.md](gotchas.md) - Common configuration errors\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-sql/gotchas.md", "content": "# R2 SQL Gotchas\n\nLimitations, troubleshooting, and common pitfalls for R2 SQL.\n\n## Critical Limitations\n\n### No Workers Binding\n\n**Cannot call R2 SQL from Workers/Pages code** - no binding exists.\n\n```typescript\n// ❌ This doesn't exist\nexport default {\n async fetch(request, env) {\n const result = await env.R2_SQL.query(\"SELECT * FROM table\"); // Not possible\n return Response.json(result);\n }\n};\n```\n\n**Solutions:**\n- HTTP API from external systems (not Workers)\n- PyIceberg/Spark via r2-data-catalog REST API\n- For Workers, use D1 or external databases\n\n### ORDER BY Limitations\n\nCan only order by:\n1. **Partition key columns** - Always supported\n2. **Aggregation functions** - Supported via shuffle strategy\n\n**Cannot order by** regular non-partition columns.\n\n```sql\n-- ✅ Valid: ORDER BY partition key\nSELECT * FROM logs.requests ORDER BY timestamp DESC LIMIT 100;\n\n-- ✅ Valid: ORDER BY aggregation\nSELECT region, SUM(amount) FROM sales.transactions\nGROUP BY region ORDER BY SUM(amount) DESC;\n\n-- ❌ Invalid: ORDER BY non-partition column\nSELECT * FROM logs.requests ORDER BY user_id;\n\n-- ❌ Invalid: ORDER BY alias (must repeat function)\nSELECT region, SUM(amount) as total FROM sales.transactions\nGROUP BY region ORDER BY total; -- Use ORDER BY SUM(amount)\n```\n\nCheck partition spec: `DESCRIBE namespace.table_name`\n\n## SQL Feature Limitations\n\n| Feature | Supported | Notes |\n|---------|-----------|-------|\n| SELECT, WHERE, GROUP BY, HAVING | ✅ | Standard support |\n| COUNT, SUM, AVG, MIN, MAX | ✅ | Standard aggregations |\n| ORDER BY partition/aggregation | ✅ | See above |\n| LIMIT | ✅ | Max 10,000 |\n| Column aliases | ❌ | No AS alias |\n| Expressions in SELECT | ❌ | No col1 + col2 |\n| ORDER BY non-partition | ❌ | Fails at runtime |\n| JOINs, subqueries, CTEs | ❌ | Denormalize at write time |\n| Window functions, UNION | ❌ | Use external engines |\n| INSERT/UPDATE/DELETE | ❌ | Use PyIceberg/Pipelines |\n| Nested columns, arrays, JSON | ❌ | Flatten at write time |\n\n**Workarounds:**\n- No JOINs: Denormalize data or use Spark/PyIceberg\n- No subqueries: Split into multiple queries\n- No aliases: Accept generated names, transform in app\n\n## Common Errors\n\n### \"Column not found\"\n**Cause:** Typo, column doesn't exist, or case mismatch \n**Solution:** `DESCRIBE namespace.table_name` to check schema\n\n### \"Type mismatch\"\n```sql\n-- ❌ Wrong types\nWHERE status = '200' -- string instead of integer\nWHERE timestamp > '2025-01-01' -- missing time/timezone\n\n-- ✅ Correct types\nWHERE status = 200\nWHERE timestamp > '2025-01-01T00:00:00Z'\n```\n\n### \"ORDER BY column not in partition key\"\n**Cause:** Ordering by non-partition column \n**Solution:** Use partition key, aggregation, or remove ORDER BY. Check: `DESCRIBE table`\n\n### \"Token authentication failed\"\n```bash\n# Check/set token\necho $WRANGLER_R2_SQL_AUTH_TOKEN\nexport WRANGLER_R2_SQL_AUTH_TOKEN=\n\n# Or .env file\necho \"WRANGLER_R2_SQL_AUTH_TOKEN=\" > .env\n```\n\n### \"Table not found\"\n```sql\n-- Verify catalog and tables\nSHOW DATABASES;\nSHOW TABLES IN namespace_name;\n```\n\nEnable catalog: `npx wrangler r2 bucket catalog enable `\n\n### \"LIMIT exceeds maximum\"\nMax LIMIT is 10,000. For pagination, use WHERE filters with partition keys.\n\n### \"No data returned\" (unexpected)\n**Debug steps:**\n1. `SELECT COUNT(*) FROM table` - verify data exists\n2. Remove WHERE filters incrementally\n3. `SELECT * FROM table LIMIT 10` - inspect actual data/types\n\n## Performance Issues\n\n### Slow Queries\n\n**Causes:** Too many partitions, large LIMIT, no filters, small files\n\n```sql\n-- ❌ Slow: No filters\nSELECT * FROM logs.requests LIMIT 10000;\n\n-- ✅ Fast: Filter on partition key\nSELECT * FROM logs.requests \nWHERE timestamp >= '2025-01-15T00:00:00Z' AND timestamp < '2025-01-16T00:00:00Z'\nLIMIT 1000;\n\n-- ✅ Faster: Multiple filters\nSELECT * FROM logs.requests \nWHERE timestamp >= '2025-01-15T00:00:00Z' AND status = 404 AND method = 'GET'\nLIMIT 1000;\n```\n\n**File optimization:**\n- Target Parquet size: 100-500MB compressed\n- Pipelines roll interval: 300+ sec (prod), 10 sec (dev)\n- Run compaction to merge small files\n\n### Query Timeout\n\n**Solution:** Add restrictive WHERE filters, reduce time range, query smaller intervals\n\n```sql\n-- ❌ Times out: Year-long aggregation\nSELECT status, COUNT(*) FROM logs.requests \nWHERE timestamp >= '2024-01-01T00:00:00Z' GROUP BY status;\n\n-- ✅ Faster: Month-long aggregation\nSELECT status, COUNT(*) FROM logs.requests \nWHERE timestamp >= '2025-01-01T00:00:00Z' AND timestamp < '2025-02-01T00:00:00Z'\nGROUP BY status;\n```\n\n## Best Practices\n\n### Partitioning\n- **Time-series:** Partition by day/hour on timestamp\n- **Avoid:** High-cardinality keys (user_id), >10,000 partitions\n\n```python\nfrom pyiceberg.partitioning import PartitionSpec, PartitionField\nfrom pyiceberg.transforms import DayTransform\n\nPartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name=\"day\"))\n```\n\n### Query Writing\n- **Always use LIMIT** for early termination\n- **Filter on partition keys first** for pruning\n- **Combine filters with AND** for more pruning\n\n```sql\n-- Good\nWHERE timestamp >= '2025-01-15T00:00:00Z' AND status = 404 AND method = 'GET' LIMIT 100\n```\n\n### Type Safety\n- Quote strings: `'GET'` not `GET`\n- RFC3339 timestamps: `'2025-01-01T00:00:00Z'` not `'2025-01-01'`\n- ISO dates: `'2025-01-15'` not `'01/15/2025'`\n\n### Data Organization\n- **Pipelines:** Dev `roll_file_time: 10`, Prod `roll_file_time: 300+`\n- **Compression:** Use `zstd`\n- **Maintenance:** Compaction for small files, expire old snapshots\n\n## Debugging Checklist\n\n1. `npx wrangler r2 bucket catalog enable ` - Verify catalog\n2. `echo $WRANGLER_R2_SQL_AUTH_TOKEN` - Check token\n3. `SHOW DATABASES` - List namespaces\n4. `SHOW TABLES IN namespace` - List tables\n5. `DESCRIBE namespace.table` - Check schema\n6. `SELECT COUNT(*) FROM namespace.table` - Verify data\n7. `SELECT * FROM namespace.table LIMIT 10` - Test simple query\n8. Add filters incrementally\n\n## See Also\n\n- [api.md](api.md) - SQL syntax\n- [patterns.md](patterns.md) - Query optimization\n- [configuration.md](configuration.md) - Setup\n- [Cloudflare R2 SQL Docs](https://developers.cloudflare.com/r2-sql/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/r2-sql/patterns.md", "content": "# R2 SQL Patterns\n\nCommon patterns, use cases, and integration examples for R2 SQL.\n\n## Wrangler CLI Query\n\n```bash\n# Basic query\nnpx wrangler r2 sql query \"my-bucket\" \"SELECT * FROM default.logs LIMIT 10\"\n\n# Multi-line query\nnpx wrangler r2 sql query \"my-bucket\" \"\n SELECT status, COUNT(*), AVG(response_time)\n FROM logs.http_requests\n WHERE timestamp >= '2025-01-01T00:00:00Z'\n GROUP BY status\n ORDER BY COUNT(*) DESC\n LIMIT 100\n\"\n\n# Use environment variable\nexport R2_SQL_WAREHOUSE=\"my-bucket\"\nnpx wrangler r2 sql query \"$R2_SQL_WAREHOUSE\" \"SELECT * FROM default.logs\"\n```\n\n## HTTP API Query\n\nFor programmatic access from external systems (not Workers - see gotchas.md).\n\n```bash\ncurl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"warehouse\": \"my-bucket\",\n \"query\": \"SELECT * FROM default.my_table WHERE status = 200 LIMIT 100\"\n }'\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"result\": [{\"user_id\": \"user_123\", \"timestamp\": \"2025-01-15T10:30:00Z\", \"status\": 200}],\n \"errors\": []\n}\n```\n\n## Pipelines Integration\n\nStream data to Iceberg tables via Pipelines, then query with R2 SQL.\n\n```bash\n# Setup pipeline (select Data Catalog Table destination)\nnpx wrangler pipelines setup\n\n# Key settings:\n# - Destination: Data Catalog Table\n# - Compression: zstd (recommended)\n# - Roll file time: 300+ sec (production), 10 sec (dev)\n\n# Send data to pipeline\ncurl -X POST https://{stream-id}.ingest.cloudflare.com \\\n -H \"Content-Type: application/json\" \\\n -d '[{\"user_id\": \"user_123\", \"event_type\": \"purchase\", \"timestamp\": \"2025-01-15T10:30:00Z\", \"amount\": 29.99}]'\n\n# Query ingested data (wait for roll interval)\nnpx wrangler r2 sql query \"my-bucket\" \"\n SELECT event_type, COUNT(*), SUM(amount)\n FROM default.events\n WHERE timestamp >= '2025-01-15T00:00:00Z'\n GROUP BY event_type\n\"\n```\n\nSee [pipelines/patterns.md](../pipelines/patterns.md) for detailed setup.\n\n## PyIceberg Integration\n\nCreate and populate Iceberg tables with PyIceberg, then query with R2 SQL.\n\n```python\nfrom pyiceberg.catalog.rest import RestCatalog\nimport pyarrow as pa\nimport pandas as pd\n\n# Setup catalog\ncatalog = RestCatalog(\n name=\"my_catalog\",\n warehouse=\"my-bucket\",\n uri=\"https://.r2.cloudflarestorage.com/iceberg/my-bucket\",\n token=\"\",\n)\ncatalog.create_namespace_if_not_exists(\"analytics\")\n\n# Create table\nschema = pa.schema([\n pa.field(\"user_id\", pa.string(), nullable=False),\n pa.field(\"event_time\", pa.timestamp(\"us\", tz=\"UTC\"), nullable=False),\n pa.field(\"page_views\", pa.int64(), nullable=False),\n])\ntable = catalog.create_table((\"analytics\", \"user_metrics\"), schema=schema)\n\n# Append data\ndf = pd.DataFrame({\n \"user_id\": [\"user_1\", \"user_2\"],\n \"event_time\": pd.to_datetime([\"2025-01-15 10:00:00\", \"2025-01-15 11:00:00\"], utc=True),\n \"page_views\": [10, 25],\n})\ntable.append(pa.Table.from_pandas(df, schema=schema))\n```\n\nQuery with R2 SQL:\n```bash\nnpx wrangler r2 sql query \"my-bucket\" \"\n SELECT user_id, SUM(page_views)\n FROM analytics.user_metrics\n WHERE event_time >= '2025-01-15T00:00:00Z'\n GROUP BY user_id\n\"\n```\n\nSee [r2-data-catalog/patterns.md](../r2-data-catalog/patterns.md) for advanced PyIceberg patterns.\n\n## Use Cases\n\n### Log Analytics\n```sql\n-- Error rate by endpoint\nSELECT path, COUNT(*), SUM(CASE WHEN status >= 400 THEN 1 ELSE 0 END) as errors\nFROM logs.http_requests\nWHERE timestamp BETWEEN '2025-01-01T00:00:00Z' AND '2025-01-31T23:59:59Z'\nGROUP BY path ORDER BY errors DESC LIMIT 20;\n\n-- Response time stats\nSELECT method, MIN(response_time_ms), AVG(response_time_ms), MAX(response_time_ms)\nFROM logs.http_requests WHERE timestamp >= '2025-01-15T00:00:00Z' GROUP BY method;\n\n-- Traffic by status\nSELECT status, COUNT(*) FROM logs.http_requests\nWHERE timestamp >= '2025-01-15T00:00:00Z' AND method = 'GET'\nGROUP BY status ORDER BY COUNT(*) DESC;\n```\n\n### Fraud Detection\n```sql\n-- High-value transactions\nSELECT location, COUNT(*), SUM(amount), AVG(amount)\nFROM fraud.transactions WHERE transaction_timestamp >= '2025-01-01T00:00:00Z' AND amount > 1000.0\nGROUP BY location ORDER BY SUM(amount) DESC LIMIT 20;\n\n-- Flagged transactions\nSELECT merchant_category, COUNT(*), AVG(amount) FROM fraud.transactions\nWHERE is_fraud_flag = true AND transaction_timestamp >= '2025-01-01T00:00:00Z'\nGROUP BY merchant_category HAVING COUNT(*) > 10 ORDER BY COUNT(*) DESC;\n```\n\n### Business Intelligence\n```sql\n-- Sales by department\nSELECT department, SUM(revenue), AVG(revenue), COUNT(*) FROM sales.transactions\nWHERE sale_date >= '2024-01-01' GROUP BY department ORDER BY SUM(revenue) DESC LIMIT 10;\n\n-- Product performance\nSELECT category, COUNT(DISTINCT product_id), SUM(units_sold), SUM(revenue)\nFROM sales.product_sales WHERE sale_date BETWEEN '2024-10-01' AND '2024-12-31'\nGROUP BY category ORDER BY SUM(revenue) DESC;\n```\n\n## Connecting External Engines\n\nR2 Data Catalog exposes Iceberg REST API. Connect Spark, Snowflake, Trino, DuckDB, etc.\n\n```scala\n// Apache Spark example\nval spark = SparkSession.builder()\n .config(\"spark.sql.catalog.my_catalog\", \"org.apache.iceberg.spark.SparkCatalog\")\n .config(\"spark.sql.catalog.my_catalog.catalog-impl\", \"org.apache.iceberg.rest.RESTCatalog\")\n .config(\"spark.sql.catalog.my_catalog.uri\", \"https://.r2.cloudflarestorage.com/iceberg/my-bucket\")\n .config(\"spark.sql.catalog.my_catalog.token\", \"\")\n .getOrCreate()\n\nspark.sql(\"SELECT * FROM my_catalog.default.my_table LIMIT 10\").show()\n```\n\nSee [r2-data-catalog/patterns.md](../r2-data-catalog/patterns.md) for more engines.\n\n## Performance Optimization\n\n### Partitioning\n- **Time-series:** day/hour on timestamp\n- **Geographic:** region/country\n- **Avoid:** High-cardinality keys (user_id)\n\n```python\nfrom pyiceberg.partitioning import PartitionSpec, PartitionField\nfrom pyiceberg.transforms import DayTransform\n\nPartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name=\"day\"))\n```\n\n### Query Optimization\n- **Always use LIMIT** for early termination\n- **Filter on partition keys first**\n- **Multiple filters** for better pruning\n\n```sql\n-- Better: Multiple filters on partition key\nSELECT * FROM logs.requests \nWHERE timestamp >= '2025-01-15T00:00:00Z' AND status = 404 AND method = 'GET' LIMIT 100;\n```\n\n### File Organization\n- **Pipelines roll:** Dev 10-30s, Prod 300+s\n- **Target Parquet:** 100-500MB compressed\n\n## See Also\n\n- [api.md](api.md) - SQL syntax reference\n- [gotchas.md](gotchas.md) - Limitations and troubleshooting\n- [r2-data-catalog/patterns.md](../r2-data-catalog/patterns.md) - PyIceberg advanced patterns\n- [pipelines/patterns.md](../pipelines/patterns.md) - Streaming ingestion patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtime-sfu/README.md", "content": "# Cloudflare Realtime SFU Reference\n\nExpert guidance for building real-time audio/video/data applications using Cloudflare Realtime SFU (Selective Forwarding Unit).\n\n## Reading Order\n\n| Task | Files | ~Tokens |\n|------|-------|---------|\n| New project | README → configuration | ~1200 |\n| Implement publish/subscribe | README → api | ~1600 |\n| Add PartyTracks | patterns (PartyTracks section) | ~800 |\n| Build presence system | patterns (DO section) | ~800 |\n| Debug connection issues | gotchas | ~700 |\n| Scale to millions | patterns (Cascading section) | ~600 |\n| Add simulcast | patterns (Advanced section) | ~500 |\n| Configure TURN | configuration (TURN section) | ~400 |\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, environment variables, Wrangler config\n- **[api.md](api.md)** - Sessions, tracks, endpoints, request/response patterns\n- **[patterns.md](patterns.md)** - Architecture patterns, use cases, integration examples\n- **[gotchas.md](gotchas.md)** - Common issues, debugging, performance, security\n\n## Quick Start\n\nCloudflare Realtime SFU: WebRTC infrastructure on global network (310+ cities). Anycast routing, no regional constraints, pub/sub model.\n\n**Core concepts:**\n- **Sessions:** WebRTC PeerConnection to Cloudflare edge\n- **Tracks:** Audio/video/data channels you publish or subscribe to\n- **No rooms:** Build presence layer yourself via track sharing (see patterns.md)\n\n**Mental model:** Your client establishes one WebRTC session, publishes tracks (audio/video), shares track IDs via your backend, others subscribe to your tracks using track IDs + your session ID.\n\n## Choose Your Approach\n\n| Approach | When to Use | Complexity |\n|----------|-------------|------------|\n| **PartyTracks** | Production apps with device switching, React | Low - Observable-based, handles reconnections |\n| **Raw API** | Custom requirements, non-browser, learning | Medium - Full control, manual WebRTC lifecycle |\n| **RealtimeKit** | End-to-end SDK with UI components | Lowest - Managed state, React hooks |\n\n**Recommendation:** Start with PartyTracks for most production applications. See patterns.md for PartyTracks examples.\n\n## SFU vs RealtimeKit\n\n- **Realtime SFU:** WebRTC infrastructure (this reference). Build your own signaling, presence, UI.\n- **RealtimeKit:** SDK layer on top of SFU. Includes React hooks, state management, UI components. Part of Cloudflare AI platform.\n\nUse SFU directly when you need custom signaling or non-React framework. Use RealtimeKit for faster development with React.\n\n## Setup\n\nDashboard: https://dash.cloudflare.com/?to=/:account/calls\n\nGet `CALLS_APP_ID` and `CALLS_APP_SECRET` from dashboard, then see configuration.md for deployment.\n\n## See Also\n\n- [Orange Meets Demo](https://demo.orange.cloudflare.dev/)\n- [Orange Source](https://github.com/cloudflare/orange)\n- [Calls Examples](https://github.com/cloudflare/calls-examples)\n- [API Reference](https://developers.cloudflare.com/api/resources/calls/)\n- [RealtimeKit Docs](https://developers.cloudflare.com/workers-ai/realtimekit/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtime-sfu/api.md", "content": "# API Reference\n\n## Authentication\n\n```bash\ncurl -X POST 'https://rtc.live/v1/apps/${CALLS_APP_ID}/sessions/new' \\\n -H \"Authorization: Bearer ${CALLS_APP_SECRET}\"\n```\n\n## Core Concepts\n\n**Sessions:** PeerConnection to Cloudflare edge \n**Tracks:** Media/data channels (audio/video/datachannel) \n**No rooms:** Build presence via track sharing\n\n## Client Libraries\n\n**PartyTracks (Recommended):** Observable-based client library for production use. Handles device changes, network switches, ICE restarts automatically. Push/pull API with React hooks. See patterns.md for full examples.\n\n```bash\nnpm install partytracks @cloudflare/calls\n```\n\n**Raw API:** Direct HTTP + WebRTC for custom requirements (documented below).\n\n## Endpoints\n\n### Create Session\n```http\nPOST /v1/apps/{appId}/sessions/new\n→ {sessionId, sessionDescription}\n```\n\n### Add Track (Publish)\n```http\nPOST /v1/apps/{appId}/sessions/{sessionId}/tracks/new\nBody: {\n sessionDescription: {sdp, type: \"offer\"},\n tracks: [{location: \"local\", trackName: \"my-video\"}]\n}\n→ {sessionDescription, tracks: [{trackName}]}\n```\n\n### Add Track (Subscribe)\n```http\nPOST /v1/apps/{appId}/sessions/{sessionId}/tracks/new\nBody: {\n tracks: [{\n location: \"remote\",\n trackName: \"remote-track-id\",\n sessionId: \"other-session-id\"\n }]\n}\n→ {sessionDescription} (server offer)\n```\n\n### Renegotiate\n```http\nPUT /v1/apps/{appId}/sessions/{sessionId}/renegotiate\nBody: {sessionDescription: {sdp, type: \"answer\"}}\n```\n\n### Close Tracks\n```http\nPUT /v1/apps/{appId}/sessions/{sessionId}/tracks/close\nBody: {tracks: [{trackName}]}\n→ {requiresImmediateRenegotiation: boolean}\n```\n\n### Get Session\n```http\nGET /v1/apps/{appId}/sessions/{sessionId}\n→ {sessionId, tracks: TrackMetadata[]}\n```\n\n## TypeScript Types\n\n```typescript\ninterface TrackMetadata {\n trackName: string;\n location: \"local\" | \"remote\";\n sessionId?: string; // For remote tracks\n mid?: string; // WebRTC mid\n}\n```\n\n## WebRTC Flow\n\n```typescript\n// 1. Create PeerConnection\nconst pc = new RTCPeerConnection({\n iceServers: [{urls: 'stun:stun.cloudflare.com:3478'}]\n});\n\n// 2. Add tracks\nconst stream = await navigator.mediaDevices.getUserMedia({video: true, audio: true});\nstream.getTracks().forEach(track => pc.addTrack(track, stream));\n\n// 3. Create offer\nconst offer = await pc.createOffer();\nawait pc.setLocalDescription(offer);\n\n// 4. Send to backend → Cloudflare API\nconst response = await fetch('/api/new-session', {\n method: 'POST',\n body: JSON.stringify({sdp: offer.sdp})\n});\n\n// 5. Set remote answer\nconst {sessionDescription} = await response.json();\nawait pc.setRemoteDescription(sessionDescription);\n```\n\n## Publishing\n\n```typescript\nconst offer = await pc.createOffer();\nawait pc.setLocalDescription(offer);\n\nconst res = await fetch(`/api/sessions/${sessionId}/tracks`, {\n method: 'POST',\n body: JSON.stringify({\n sdp: offer.sdp,\n tracks: [{location: 'local', trackName: 'my-video'}]\n })\n});\n\nconst {sessionDescription, tracks} = await res.json();\nawait pc.setRemoteDescription(sessionDescription);\nconst publishedTrackId = tracks[0].trackName; // Share with others\n```\n\n## Subscribing\n\n```typescript\nconst res = await fetch(`/api/sessions/${sessionId}/tracks`, {\n method: 'POST',\n body: JSON.stringify({\n tracks: [{location: 'remote', trackName: remoteTrackId, sessionId: remoteSessionId}]\n })\n});\n\nconst {sessionDescription} = await res.json();\nawait pc.setRemoteDescription(sessionDescription);\n\nconst answer = await pc.createAnswer();\nawait pc.setLocalDescription(answer);\n\nawait fetch(`/api/sessions/${sessionId}/renegotiate`, {\n method: 'PUT',\n body: JSON.stringify({sdp: answer.sdp})\n});\n\npc.ontrack = (event) => {\n const [remoteStream] = event.streams;\n videoElement.srcObject = remoteStream;\n};\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtime-sfu/configuration.md", "content": "# Configuration & Deployment\n\n## Dashboard Setup\n\n1. Navigate to https://dash.cloudflare.com/?to=/:account/calls\n2. Click \"Create Application\" (or use existing app)\n3. Copy `CALLS_APP_ID` from dashboard\n4. Generate and copy `CALLS_APP_SECRET` (treat as sensitive credential)\n5. Use credentials in Wrangler config or environment variables below\n\n## Dependencies\n\n**Backend (Workers):** Built-in fetch API, no additional packages required\n\n**Client (PartyTracks):**\n```bash\nnpm install partytracks @cloudflare/calls\n```\n\n**Client (React + PartyTracks):**\n```bash\nnpm install partytracks @cloudflare/calls observable-hooks\n# Observable hooks: useObservableAsValue, useValueAsObservable\n```\n\n**Client (Raw API):** Native browser WebRTC API only\n\n## Wrangler Setup\n\n```jsonc\n{\n \"name\": \"my-calls-app\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \"vars\": {\n \"CALLS_APP_ID\": \"your-app-id\",\n \"MAX_WEBCAM_BITRATE\": \"1200000\",\n \"MAX_WEBCAM_FRAMERATE\": \"24\",\n \"MAX_WEBCAM_QUALITY_LEVEL\": \"1080\"\n },\n // Set secret: wrangler secret put CALLS_APP_SECRET\n \"durable_objects\": {\n \"bindings\": [\n {\n \"name\": \"ROOM\",\n \"class_name\": \"Room\"\n }\n ]\n }\n}\n```\n\n## Deploy\n\n```bash\nwrangler login\nwrangler secret put CALLS_APP_SECRET\nwrangler deploy\n```\n\n## Environment Variables\n\n**Required:**\n- `CALLS_APP_ID`: From dashboard\n- `CALLS_APP_SECRET`: From dashboard (secret)\n\n**Optional:**\n- `MAX_WEBCAM_BITRATE` (default: 1200000)\n- `MAX_WEBCAM_FRAMERATE` (default: 24)\n- `MAX_WEBCAM_QUALITY_LEVEL` (default: 1080)\n- `TURN_SERVICE_ID`: TURN service\n- `TURN_SERVICE_TOKEN`: TURN auth (secret)\n\n## TURN Configuration\n\n```javascript\nconst pc = new RTCPeerConnection({\n iceServers: [\n { urls: 'stun:stun.cloudflare.com:3478' },\n {\n urls: [\n 'turn:turn.cloudflare.com:3478?transport=udp',\n 'turn:turn.cloudflare.com:3478?transport=tcp',\n 'turns:turn.cloudflare.com:5349?transport=tcp'\n ],\n username: turnUsername,\n credential: turnCredential\n }\n ],\n bundlePolicy: 'max-bundle', // Recommended: reduces overhead\n iceTransportPolicy: 'all' // Use 'relay' to force TURN (testing only)\n});\n```\n\n**Ports:** 3478 (UDP/TCP), 53 (UDP), 80 (TCP), 443 (TLS), 5349 (TLS)\n\n**When to use TURN:** Required for restrictive corporate firewalls/networks that block UDP. ~5-10% of connections fallback to TURN. STUN works for most users.\n\n**ICE candidate filtering:** Cloudflare handles candidate filtering automatically. No need to manually filter candidates.\n\n## Durable Object Boilerplate\n\nMinimal presence system:\n\n```typescript\nexport class Room {\n private sessions = new Map();\n\n async fetch(req: Request) {\n const {pathname} = new URL(req.url);\n const body = await req.json();\n \n if (pathname === '/join') {\n this.sessions.set(body.sessionId, {userId: body.userId, tracks: []});\n return Response.json({participants: this.sessions.size});\n }\n \n if (pathname === '/publish') {\n this.sessions.get(body.sessionId)?.tracks.push(...body.tracks);\n // Broadcast to others via WebSocket (not shown)\n return new Response('OK');\n }\n \n return new Response('Not found', {status: 404});\n }\n}\n```\n\n## Environment Validation\n\nCheck credentials before first API call:\n\n```typescript\nif (!env.CALLS_APP_ID || !env.CALLS_APP_SECRET) {\n throw new Error('CALLS_APP_ID and CALLS_APP_SECRET required');\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtime-sfu/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"Slow initial connect (~1.8s)\"\n\n**Cause:** First STUN delayed during consensus forming (normal behavior)\n**Solution:** Subsequent connections are faster. CF detects DTLS ClientHello early to compensate.\n\n### \"No media flow\"\n\n**Cause:** SDP exchange incomplete, connection not established, tracks not added before offer, browser permissions missing\n**Solution:** \n1. Verify SDP exchange complete\n2. Check `pc.connectionState === 'connected'`\n3. Ensure tracks added before creating offer\n4. Confirm browser permissions granted\n5. Use `chrome://webrtc-internals` for debugging\n\n### \"Track not receiving\"\n\n**Cause:** Track not published, track ID not shared, session IDs mismatch, `pc.ontrack` not set, renegotiation needed\n**Solution:** \n1. Verify track published successfully\n2. Confirm track ID shared between peers\n3. Check session IDs match\n4. Set `pc.ontrack` handler before answer\n5. Trigger renegotiation if needed\n\n### \"ICE connection failed\"\n\n**Cause:** Network changed, firewall blocked UDP, TURN needed, transient network issue\n**Solution:**\n```typescript\npc.oniceconnectionstatechange = async () => {\n if (pc.iceConnectionState === 'failed') {\n console.warn('ICE failed, attempting restart');\n await pc.restartIce(); // Triggers new ICE gathering\n \n // Create new offer with ICE restart flag\n const offer = await pc.createOffer({iceRestart: true});\n await pc.setLocalDescription(offer);\n \n // Send to backend → Cloudflare API\n await fetch(`/api/sessions/${sessionId}/renegotiate`, {\n method: 'PUT',\n body: JSON.stringify({sdp: offer.sdp})\n });\n }\n};\n```\n\n### \"Track stuck/frozen\"\n\n**Cause:** Sender paused track, network congestion, codec mismatch, mobile browser backgrounded\n**Solution:**\n1. Check `track.enabled` and `track.readyState === 'live'`\n2. Verify sender active: `pc.getSenders().find(s => s.track === track)`\n3. Check stats for packet loss/jitter (see patterns.md)\n4. On mobile: Re-acquire tracks when app foregrounded\n5. Test with different codecs if persistent\n\n### \"Network change disconnects call\"\n\n**Cause:** Mobile switching WiFi↔cellular, laptop changing networks\n**Solution:**\n```typescript\n// Listen for network changes\nif ('connection' in navigator) {\n (navigator as any).connection.addEventListener('change', async () => {\n console.log('Network changed');\n await pc.restartIce(); // Use ICE restart pattern above\n });\n}\n\n// Or use PartyTracks (handles automatically)\n```\n\n## Retry with Exponential Backoff\n\n```typescript\nasync function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {\n for (let i = 0; i < maxRetries; i++) {\n try {\n const res = await fetch(url, options);\n if (res.ok) return res;\n if (res.status >= 500) throw new Error('Server error');\n return res; // Client error, don't retry\n } catch (err) {\n if (i === maxRetries - 1) throw err;\n const delay = Math.min(1000 * 2 ** i, 10000); // Cap at 10s\n await new Promise(resolve => setTimeout(resolve, delay));\n }\n }\n}\n```\n\n## Debugging with chrome://webrtc-internals\n\n1. Open `chrome://webrtc-internals` in Chrome/Edge\n2. Find your PeerConnection in the list\n3. Check **Stats graphs** for packet loss, jitter, bandwidth\n4. Check **ICE candidate pairs**: Look for `succeeded` state, relay vs host candidates\n5. Check **getStats**: Raw metrics for inbound/outbound RTP\n6. Look for errors in **Event log**: `iceConnectionState`, `connectionState` changes\n7. Export data with \"Download the PeerConnection updates and stats data\" button\n8. Common issues visible here: ICE failures, high packet loss, bitrate drops\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Egress (Free) | 1TB/month | Per account |\n| Egress (Paid) | $0.05/GB | After free tier |\n| Inbound traffic | Free | All plans |\n| TURN service | Free | Included with SFU |\n| Participants | No hard limit | Client bandwidth/CPU bound (typically 10-50 tracks) |\n| Tracks per session | No hard limit | Client resources limited |\n| Session duration | No hard limit | Production calls run for hours |\n| WebRTC ports | UDP 1024-65535 | Outbound only, required for media |\n| API rate limit | 600 req/min | Per app, burst allowed |\n\n## Security Checklist\n\n- ✅ **Never expose** `CALLS_APP_SECRET` to client\n- ✅ **Validate user identity** in backend before creating sessions\n- ✅ **Implement auth tokens** for session access (JWT in custom header)\n- ✅ **Rate limit** session creation endpoints\n- ✅ **Expire sessions** server-side after inactivity\n- ✅ **Validate track IDs** before subscribing (prevent unauthorized access)\n- ✅ **Use HTTPS** for all signaling (API calls)\n- ✅ **Enable DTLS-SRTP** (automatic with Cloudflare, encrypts media)\n- ⚠️ **Consider E2EE** for sensitive content (implement client-side with Insertable Streams API)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtime-sfu/patterns.md", "content": "# Patterns & Use Cases\n\n## Architecture\n\n```\nClient (WebRTC) <---> CF Edge <---> Backend (HTTP)\n |\n CF Backbone (310+ DCs)\n |\n Other Edges <---> Other Clients\n```\n\nAnycast: Last-mile <50ms (95%), no region select, NACK shield, distributed consensus\n\nCascading trees auto-scale to millions:\n```\nPublisher -> Edge A -> Edge B -> Sub1\n \\-> Edge C -> Sub2,3\n```\n\n## Use Cases\n\n**1:1:** A creates session+publishes, B creates+subscribes to A+publishes, A subscribes to B\n**N:N:** All create session+publish, backend broadcasts track IDs, all subscribe to others\n**1:N:** Publisher creates+publishes, viewers each create+subscribe (no fan-out limit)\n**Breakout:** Same PeerConnection! Backend closes/adds tracks, no recreation\n\n## PartyTracks (Recommended)\n\nObservable-based client with automatic device/network handling:\n\n```typescript\nimport {PartyTracks} from 'partytracks';\n\n// Create client\nconst pt = new PartyTracks({\n apiUrl: '/api/calls',\n sessionId: 'my-session',\n onTrack: (track, peer) => {\n const video = document.getElementById(`video-${peer.id}`) as HTMLVideoElement;\n video.srcObject = new MediaStream([track]);\n }\n});\n\n// Publish camera (push API)\nconst camera = await pt.getCamera(); // Auto-requests permissions, handles device changes\nawait pt.publishTrack(camera, {trackName: 'my-camera'});\n\n// Subscribe to remote track (pull API)\nawait pt.subscribeToTrack({trackName: 'remote-camera', sessionId: 'other-session'});\n\n// React hook example\nimport {useObservableAsValue} from 'observable-hooks';\n\nfunction VideoCall() {\n const localTracks = useObservableAsValue(pt.localTracks$);\n const remoteTracks = useObservableAsValue(pt.remoteTracks$);\n \n return
{/* Render tracks */}
;\n}\n\n// Screenshare\nconst screen = await pt.getScreenshare();\nawait pt.publishTrack(screen, {trackName: 'my-screen'});\n\n// Handle device changes (automatic)\n// PartyTracks detects device changes (e.g., Bluetooth headset) and renegotiates\n```\n\n## Backend\n\nExpress:\n```js\napp.post('/api/new-session', async (req, res) => {\n const r = await fetch(`${CALLS_API}/apps/${process.env.CALLS_APP_ID}/sessions/new`,\n {method: 'POST', headers: {'Authorization': `Bearer ${process.env.CALLS_APP_SECRET}`}});\n res.json(await r.json());\n});\n```\n\nWorkers: Same pattern, use `env.CALLS_APP_ID` and `env.CALLS_APP_SECRET`\n\nDO Presence: See configuration.md for boilerplate\n\n## Audio Level Detection\n\n```typescript\n// Attach analyzer to audio track\nfunction attachAudioLevelDetector(track: MediaStreamTrack) {\n const ctx = new AudioContext();\n const analyzer = ctx.createAnalyser();\n const src = ctx.createMediaStreamSource(new MediaStream([track]));\n src.connect(analyzer);\n \n const data = new Uint8Array(analyzer.frequencyBinCount);\n const checkLevel = () => {\n analyzer.getByteFrequencyData(data);\n const level = data.reduce((a, b) => a + b) / data.length;\n if (level > 30) console.log('Speaking:', level); // Trigger UI update\n requestAnimationFrame(checkLevel);\n };\n checkLevel();\n}\n```\n\n## Connection Quality Monitoring\n\n```typescript\npc.getStats().then(stats => {\n stats.forEach(report => {\n if (report.type === 'inbound-rtp' && report.kind === 'video') {\n const {packetsLost, packetsReceived, jitter} = report;\n const lossRate = packetsLost / (packetsLost + packetsReceived);\n if (lossRate > 0.05) console.warn('High packet loss:', lossRate);\n if (jitter > 100) console.warn('High jitter:', jitter);\n }\n });\n});\n```\n\n## Stage Management (Limit Visible Participants)\n\n```typescript\n// Subscribe to top 6 active speakers only\nlet activeSubscriptions = new Set();\n\nfunction updateStage(topSpeakers: string[]) {\n const toAdd = topSpeakers.filter(id => !activeSubscriptions.has(id)).slice(0, 6);\n const toRemove = [...activeSubscriptions].filter(id => !topSpeakers.includes(id));\n \n toRemove.forEach(id => {\n pc.getSenders().find(s => s.track?.id === id)?.track?.stop();\n activeSubscriptions.delete(id);\n });\n \n toAdd.forEach(async id => {\n await fetch(`/api/subscribe`, {method: 'POST', body: JSON.stringify({trackId: id})});\n activeSubscriptions.add(id);\n });\n}\n```\n\n## Advanced\n\nBandwidth mgmt:\n```ts\nconst s = pc.getSenders().find(s => s.track?.kind === 'video');\nconst p = s.getParameters();\nif (!p.encodings) p.encodings = [{}];\np.encodings[0].maxBitrate = 1200000; p.encodings[0].maxFramerate = 24;\nawait s.setParameters(p);\n```\n\nSimulcast (CF auto-forwards best layer):\n```ts\npc.addTransceiver('video', {direction: 'sendonly', sendEncodings: [\n {rid: 'high', maxBitrate: 1200000},\n {rid: 'med', maxBitrate: 600000, scaleResolutionDownBy: 2},\n {rid: 'low', maxBitrate: 200000, scaleResolutionDownBy: 4}\n]});\n```\n\nDataChannel:\n```ts\nconst dc = pc.createDataChannel('chat', {ordered: true, maxRetransmits: 3});\ndc.onopen = () => dc.send(JSON.stringify({type: 'chat', text: 'Hi'}));\ndc.onmessage = (e) => console.log('RX:', JSON.parse(e.data));\n```\n\n**WHIP/WHEP:** For streaming interop (OBS → SFU, SFU → video players), use WHIP (ingest) and WHEP (egress) protocols. See Cloudflare Stream integration docs.\n\nIntegrations: R2 for recording `env.R2_BUCKET.put(...)`, Queues for analytics\n\nPerf: 100-250ms connect, ~50ms latency (95%), 200-400ms glass-to-glass, no participant limit (client: 10-50 tracks)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtimekit/README.md", "content": "# Cloudflare RealtimeKit\n\nExpert guidance for building real-time video and audio applications using **Cloudflare RealtimeKit** - a comprehensive SDK suite for adding customizable live video and voice to web or mobile applications.\n\n## Overview\n\nRealtimeKit is Cloudflare's SDK suite built on Realtime SFU, abstracting WebRTC complexity with fast integration, pre-built UI components, global performance (300+ cities), and production features (recording, transcription, chat, polls).\n\n**Use cases**: Team meetings, webinars, social video, audio calls, interactive plugins\n\n## Core Concepts\n\n- **App**: Workspace grouping meetings, participants, presets, recordings. Use separate Apps for staging/production\n- **Meeting**: Re-usable virtual room. Each join creates new **Session**\n- **Session**: Live meeting instance. Created on first join, ends after last leave\n- **Participant**: User added via REST API. Returns `authToken` for client SDK. **Do not reuse tokens**\n- **Preset**: Reusable permission/UI template (permissions, meeting type, theme). Applied at participant creation\n- **Peer ID** (`id`): Unique per session, changes on rejoin\n- **Participant ID** (`userId`): Persistent across sessions\n\n## Quick Start\n\n### 1. Create App & Meeting (Backend)\n\n```bash\n# Create app\ncurl -X POST 'https://api.cloudflare.com/client/v4/accounts//realtime/kit/apps' \\\n -H 'Authorization: Bearer ' \\\n -d '{\"name\": \"My RealtimeKit App\"}'\n\n# Create meeting\ncurl -X POST 'https://api.cloudflare.com/client/v4/accounts//realtime/kit//meetings' \\\n -H 'Authorization: Bearer ' \\\n -d '{\"title\": \"Team Standup\"}'\n\n# Add participant\ncurl -X POST 'https://api.cloudflare.com/client/v4/accounts//realtime/kit//meetings//participants' \\\n -H 'Authorization: Bearer ' \\\n -d '{\"name\": \"Alice\", \"preset_name\": \"host\"}'\n# Returns: { authToken }\n```\n\n### 2. Client Integration\n\n**React**:\n```tsx\nimport { RtkMeeting } from '@cloudflare/realtimekit-react-ui';\n\nfunction App() {\n return \" onLeave={() => {}} />;\n}\n```\n\n**Core SDK**:\n```typescript\nimport RealtimeKitClient from '@cloudflare/realtimekit';\n\nconst meeting = new RealtimeKitClient({ authToken: '', video: true, audio: true });\nawait meeting.join();\n```\n\n## Reading Order\n\n| Task | Files |\n|------|-------|\n| Quick integration | README only |\n| Custom UI | README → patterns → api |\n| Backend setup | README → configuration |\n| Debug issues | gotchas |\n| Advanced features | patterns → api |\n\n## RealtimeKit vs Realtime SFU\n\n| Choose | When |\n|--------|------|\n| **RealtimeKit** | Need pre-built UI, fast integration, React/Angular/HTML |\n| **Realtime SFU** | Building from scratch, custom WebRTC, full control |\n\nRealtimeKit is built on Realtime SFU but abstracts WebRTC complexity with UI components and SDKs.\n\n## Which Package?\n\nNeed pre-built meeting UI?\n- React → `@cloudflare/realtimekit-react-ui` (``)\n- Angular → `@cloudflare/realtimekit-angular-ui`\n- HTML/Vanilla → `@cloudflare/realtimekit-ui`\n\nNeed custom UI?\n- Core SDK → `@cloudflare/realtimekit` (RealtimeKitClient) - full control\n\nNeed raw WebRTC control?\n- See `realtime-sfu/` reference\n\n## In This Reference\n\n- [Configuration](./configuration.md) - Setup, installation, wrangler config\n- [API](./api.md) - Meeting object, REST API, SDK methods\n- [Patterns](./patterns.md) - Common workflows, code examples\n- [Gotchas](./gotchas.md) - Common issues, troubleshooting\n\n## See Also\n\n- [Workers](../workers/) - Backend integration\n- [D1](../d1/) - Meeting metadata storage\n- [R2](../r2/) - Recording storage\n- [KV](../kv/) - Session management\n\n## Reference Links\n\n- **Official Docs**: https://developers.cloudflare.com/realtime/realtimekit/\n- **API Reference**: https://developers.cloudflare.com/api/resources/realtime_kit/\n- **Examples**: https://github.com/cloudflare/realtimekit-web-examples\n- **Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtimekit/api.md", "content": "# RealtimeKit API Reference\n\nComplete API reference for Meeting object, REST endpoints, and SDK methods.\n\n## Meeting Object API\n\n### `meeting.self` - Local Participant\n\n```typescript\n// Properties: id, userId, name, audioEnabled, videoEnabled, screenShareEnabled, audioTrack, videoTrack, screenShareTracks, roomJoined, roomState\n// Methods\nawait meeting.self.enableAudio() / disableAudio() / enableVideo() / disableVideo() / enableScreenShare() / disableScreenShare()\nawait meeting.self.setName(\"Name\") // Before join only\nawait meeting.self.setDevice(device)\nconst devices = await meeting.self.getAllDevices() / getAudioDevices() / getVideoDevices() / getSpeakerDevices()\n// Events: 'roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'\nmeeting.self.on('roomJoined', () => {})\nmeeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {})\n```\n\n### `meeting.participants` - Remote Participants\n\n**Collections**:\n```typescript\nmeeting.participants.joined / active / waitlisted / pinned // Maps\nconst participants = meeting.participants.joined.toArray()\nconst count = meeting.participants.joined.size()\nconst p = meeting.participants.joined.get('peer-id')\n```\n\n**Participant Properties**:\n```typescript\nparticipant.id / userId / name\nparticipant.audioEnabled / videoEnabled / screenShareEnabled\nparticipant.audioTrack / videoTrack / screenShareTracks\n```\n\n**Events**:\n```typescript\nmeeting.participants.joined.on('participantJoined', (participant) => {})\nmeeting.participants.joined.on('participantLeft', (participant) => {})\n```\n\n### `meeting.meta` - Metadata\n```typescript\nmeeting.meta.meetingId / meetingTitle / meetingStartedTimestamp\n```\n\n### `meeting.chat` - Chat\n```typescript\nmeeting.chat.messages // Array\nawait meeting.chat.sendTextMessage(\"Hello\") / sendImageMessage(file)\nmeeting.chat.on('chatUpdate', ({ message, messages }) => {})\n```\n\n### `meeting.polls` - Polling\n```typescript\nmeeting.polls.items // Array\nawait meeting.polls.create(question, options, anonymous, hideVotes)\nawait meeting.polls.vote(pollId, optionIndex)\n```\n\n### `meeting.plugins` - Collaborative Apps\n```typescript\nmeeting.plugins.all // Array\nawait meeting.plugins.activate(pluginId) / deactivate()\n```\n\n### `meeting.ai` - AI Features\n```typescript\nmeeting.ai.transcripts // Live transcriptions (when enabled in Preset)\n```\n\n### Core Methods\n```typescript\nawait meeting.join() // Emits 'roomJoined' on meeting.self\nawait meeting.leave()\n```\n\n## TypeScript Types\n\n```typescript\nimport type { RealtimeKitClient, States, UIConfig, Participant } from '@cloudflare/realtimekit';\n\n// Main interface\ninterface RealtimeKitClient {\n self: SelfState; // Local participant (id, userId, name, audioEnabled, videoEnabled, roomJoined, roomState)\n participants: { joined, active, waitlisted, pinned }; // Reactive Maps\n chat: ChatNamespace; // messages[], sendTextMessage(), sendImageMessage()\n polls: PollsNamespace; // items[], create(), vote()\n plugins: PluginsNamespace; // all[], activate(), deactivate()\n ai: AINamespace; // transcripts[]\n meta: MetaState; // meetingId, meetingTitle, meetingStartedTimestamp\n join(): Promise;\n leave(): Promise;\n}\n\n// Participant (self & remote share same shape)\ninterface Participant {\n id: string; // Peer ID (changes on rejoin)\n userId: string; // Persistent participant ID\n name: string;\n audioEnabled: boolean;\n videoEnabled: boolean;\n screenShareEnabled: boolean;\n audioTrack: MediaStreamTrack | null;\n videoTrack: MediaStreamTrack | null;\n screenShareTracks: MediaStreamTrack[];\n}\n```\n\n## Store Architecture\n\nRealtimeKit uses reactive store (event-driven updates, live Maps):\n\n```typescript\n// Subscribe to state changes\nmeeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {});\nmeeting.participants.joined.on('participantJoined', (p) => {});\n\n// Access current state synchronously\nconst isAudioOn = meeting.self.audioEnabled;\nconst count = meeting.participants.joined.size();\n```\n\n**Key principles:** State updates emit events after changes. Use `.toArray()` sparingly. Collections are live Maps.\n\n## REST API\n\nBase: `https://api.cloudflare.com/client/v4/accounts/{account_id}/realtime/kit/{app_id}`\n\n### Meetings\n```bash\nGET /meetings # List all\nGET /meetings/{meeting_id} # Get details\nPOST /meetings # Create: {\"title\": \"...\"}\nPATCH /meetings/{meeting_id} # Update: {\"title\": \"...\", \"record_on_start\": true}\n```\n\n### Participants\n```bash\nGET /meetings/{meeting_id}/participants # List all\nGET /meetings/{meeting_id}/participants/{participant_id} # Get details\nPOST /meetings/{meeting_id}/participants # Add: {\"name\": \"...\", \"preset_name\": \"...\", \"custom_participant_id\": \"...\"}\nPATCH /meetings/{meeting_id}/participants/{participant_id} # Update: {\"name\": \"...\", \"preset_name\": \"...\"}\nDELETE /meetings/{meeting_id}/participants/{participant_id} # Delete\nPOST /meetings/{meeting_id}/participants/{participant_id}/token # Refresh token\n```\n\n### Active Session\n```bash\nGET /meetings/{meeting_id}/active-session # Get active session\nPOST /meetings/{meeting_id}/active-session/kick # Kick users: {\"user_ids\": [\"id1\", \"id2\"]}\nPOST /meetings/{meeting_id}/active-session/kick-all # Kick all\nPOST /meetings/{meeting_id}/active-session/poll # Create poll: {\"question\": \"...\", \"options\": [...], \"anonymous\": false}\n```\n\n### Recording\n```bash\nGET /recordings?meeting_id={meeting_id} # List recordings\nGET /recordings/active-recording/{meeting_id} # Get active recording\nPOST /recordings # Start: {\"meeting_id\": \"...\", \"type\": \"composite\"} (or \"track\")\nPUT /recordings/{recording_id} # Control: {\"action\": \"pause\"} (or \"resume\", \"stop\")\nPOST /recordings/track # Track recording: {\"meeting_id\": \"...\", \"layers\": [...]}\n```\n\n### Livestreaming\n```bash\nGET /livestreams?exclude_meetings=false # List all\nGET /livestreams/{livestream_id} # Get details\nPOST /meetings/{meeting_id}/livestreams # Start for meeting\nPOST /meetings/{meeting_id}/active-livestream/stop # Stop\nPOST /livestreams # Create independent: returns {ingest_server, stream_key, playback_url}\n```\n\n### Sessions & Analytics\n```bash\nGET /sessions # List all\nGET /sessions/{session_id} # Get details\nGET /sessions/{session_id}/participants # List participants\nGET /sessions/{session_id}/participants/{participant_id} # Call stats\nGET /sessions/{session_id}/chat # Download chat CSV\nGET /sessions/{session_id}/transcript # Download transcript CSV\nGET /sessions/{session_id}/summary # Get summary\nPOST /sessions/{session_id}/summary # Generate summary\nGET /analytics/daywise?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD # Day-wise analytics\nGET /analytics/livestreams/overall # Livestream analytics\n```\n\n### Webhooks\n```bash\nGET /webhooks # List all\nPOST /webhooks # Create: {\"url\": \"https://...\", \"events\": [\"session.started\", \"session.ended\"]}\nPATCH /webhooks/{webhook_id} # Update\nDELETE /webhooks/{webhook_id} # Delete\n```\n\n## Session Lifecycle\n\n```\nInitialization → Join Intent → [Waitlist?] → Meeting Screen (Stage) → Ended\n ↓ Approved\n [Rejected → Ended]\n```\n\nUI Kit handles state transitions automatically.\n\n## See Also\n\n- [Configuration](./configuration.md) - Setup and installation\n- [Patterns](./patterns.md) - Usage examples\n- [README](./README.md) - Overview and quick start\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtimekit/configuration.md", "content": "# RealtimeKit Configuration\n\nConfiguration guide for RealtimeKit setup, client SDKs, and wrangler integration.\n\n## Installation\n\n### React\n```bash\nnpm install @cloudflare/realtimekit @cloudflare/realtimekit-react-ui\n```\n\n### Angular\n```bash\nnpm install @cloudflare/realtimekit @cloudflare/realtimekit-angular-ui\n```\n\n### Web Components/HTML\n```bash\nnpm install @cloudflare/realtimekit @cloudflare/realtimekit-ui\n```\n\n## Client SDK Configuration\n\n### React UI Kit\n```tsx\nimport { RtkMeeting } from '@cloudflare/realtimekit-react-ui';\n\" onLeave={() => {}} />\n```\n\n### Angular UI Kit\n```typescript\n@Component({ template: `` })\nexport class AppComponent { authToken = ''; onLeave() {} }\n```\n\n### Web Components\n```html\n\n\n\n```\n\n### Core SDK Configuration\n```typescript\nimport RealtimeKitClient from '@cloudflare/realtimekit';\n\nconst meeting = new RealtimeKitClient({\n authToken: '',\n video: true, audio: true, autoSwitchAudioDevice: true,\n mediaConfiguration: {\n video: { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } },\n audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },\n screenshare: { width: { max: 1920 }, height: { max: 1080 }, frameRate: { ideal: 15 } }\n }\n});\nawait meeting.join();\n```\n\n## Backend Setup\n\n### Create App & Credentials\n\n**Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit\n\n**API**:\n```bash\ncurl -X POST 'https://api.cloudflare.com/client/v4/accounts//realtime/kit/apps' \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer ' \\\n -d '{\"name\": \"My RealtimeKit App\"}'\n```\n\n**Required Permissions**: API token with **Realtime / Realtime Admin** permissions\n\n### Create Presets\n\n```bash\ncurl -X POST 'https://api.cloudflare.com/client/v4/accounts//realtime/kit//presets' \\\n -H 'Authorization: Bearer ' \\\n -d '{\n \"name\": \"host\",\n \"permissions\": {\n \"canShareAudio\": true,\n \"canShareVideo\": true,\n \"canRecord\": true,\n \"canLivestream\": true,\n \"canStartStopRecording\": true\n }\n }'\n```\n\n## Wrangler Configuration\n\n### Basic Configuration\n```jsonc\n// wrangler.jsonc\n{\n \"name\": \"realtimekit-app\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date\n \"vars\": {\n \"CLOUDFLARE_ACCOUNT_ID\": \"abc123\",\n \"REALTIMEKIT_APP_ID\": \"xyz789\"\n }\n // Secrets: wrangler secret put CLOUDFLARE_API_TOKEN\n}\n```\n\n### With Database & Storage\n```jsonc\n{\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"meetings\", \"database_id\": \"d1-id\" }],\n \"r2_buckets\": [{ \"binding\": \"RECORDINGS\", \"bucket_name\": \"recordings\" }],\n \"kv_namespaces\": [{ \"binding\": \"SESSIONS\", \"id\": \"kv-id\" }]\n}\n```\n\n### Multi-Environment\n```bash\n# Deploy to environments\nwrangler deploy --env staging\nwrangler deploy --env production\n```\n\n## TURN Service Configuration\n\nRealtimeKit can use Cloudflare's TURN service for connectivity through restrictive networks:\n\n```jsonc\n// wrangler.jsonc\n{\n \"vars\": {\n \"TURN_SERVICE_ID\": \"your_turn_service_id\"\n }\n // Set secret: wrangler secret put TURN_SERVICE_TOKEN\n}\n```\n\nTURN automatically configured when enabled in account - no client-side changes needed.\n\n## Theming & Design Tokens\n\n```typescript\nimport type { UIConfig } from '@cloudflare/realtimekit';\n\nconst uiConfig: UIConfig = {\n designTokens: {\n colors: {\n brand: { 500: '#0066ff', 600: '#0052cc' },\n background: { 1000: '#1A1A1A', 900: '#2D2D2D' },\n text: { 1000: '#FFFFFF', 900: '#E0E0E0' }\n },\n borderRadius: 'extra-rounded', // 'rounded' | 'extra-rounded' | 'sharp'\n theme: 'dark' // 'light' | 'dark'\n },\n logo: { url: 'https://example.com/logo.png', altText: 'Company' }\n};\n\n// Apply to React\n {}} />\n\n// Or use CSS variables\n// :root { --rtk-color-brand-500: #0066ff; --rtk-border-radius: 12px; }\n```\n\n## Internationalization (i18n)\n\n### Custom Language Strings\n```typescript\nimport { useLanguage } from '@cloudflare/realtimekit-ui';\n\nconst customLanguage = {\n 'join': 'Entrar',\n 'leave': 'Salir',\n 'mute': 'Silenciar',\n 'unmute': 'Activar audio',\n 'turn_on_camera': 'Encender cámara',\n 'turn_off_camera': 'Apagar cámara',\n 'share_screen': 'Compartir pantalla',\n 'stop_sharing': 'Dejar de compartir'\n};\n\nconst t = useLanguage(customLanguage);\n\n// React usage\n {}} />\n```\n\n### Supported Locales\nDefault locales available: `en`, `es`, `fr`, `de`, `pt`, `ja`, `zh`\n\n```typescript\nimport { setLocale } from '@cloudflare/realtimekit-ui';\nsetLocale('es'); // Switch to Spanish\n```\n\n## See Also\n\n- [API](./api.md) - Meeting APIs, REST endpoints\n- [Patterns](./patterns.md) - Backend integration examples\n- [README](./README.md) - Overview and quick start\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtimekit/gotchas.md", "content": "# RealtimeKit Gotchas & Troubleshooting\n\n## Common Errors\n\n### \"Cannot connect to meeting\"\n\n**Cause:** Auth token invalid/expired, API credentials lack permissions, or network blocks WebRTC\n**Solution:**\nVerify token validity, check API token has **Realtime / Realtime Admin** permissions, enable TURN service for restrictive networks\n\n### \"No video/audio tracks\"\n\n**Cause:** Browser permissions not granted, video/audio not enabled, device in use, or device unavailable\n**Solution:**\nRequest browser permissions explicitly, verify initialization config, use `meeting.self.getAllDevices()` to debug, close other apps using device\n\n### \"Participant count mismatched\"\n\n**Cause:** `meeting.participants` doesn't include `meeting.self`\n**Solution:** Total count = `meeting.participants.joined.size() + 1`\n\n### \"Events not firing\"\n\n**Cause:** Listeners registered after actions, incorrect event name, or wrong namespace\n**Solution:**\nRegister listeners before calling `meeting.join()`, check event names against docs, verify correct namespace\n\n### \"CORS errors in API calls\"\n\n**Cause:** Making REST API calls from client-side\n**Solution:** All REST API calls **must** be server-side (Workers, backend). Never expose API tokens to clients.\n\n### \"Preset not applying\"\n\n**Cause:** Preset doesn't exist, name mismatch (case-sensitive), or participant created before preset\n**Solution:**\nVerify preset exists via Dashboard or API, check exact spelling and case, create preset before adding participants\n\n### \"Token reuse error\"\n\n**Cause:** Reusing participant tokens across sessions\n**Solution:** Generate fresh token per session. Use refresh endpoint if token expires during session.\n\n### \"Video quality poor\"\n\n**Cause:** Insufficient bandwidth, resolution/bitrate too high, or CPU overload\n**Solution:**\nLower `mediaConfiguration.video` resolution/frameRate, monitor network conditions, reduce participant count or grid size\n\n### \"Echo or audio feedback\"\n\n**Cause:** Multiple devices picking up same audio source\n**Solution:**\n- Lower `mediaConfiguration.video` resolution/frameRate\n- Monitor network conditions\n- Reduce participant count or grid size\n\n### Issue: Echo or audio feedback\n**Cause**: Multiple devices picking up same audio source\n\n**Solutions**:\nEnable `echoCancellation: true` in `mediaConfiguration.audio`, use headphones, mute when not speaking\n\n### \"Screen share not working\"\n\n**Cause:** Browser doesn't support screen sharing API, permission denied, or wrong `displaySurface` config\n**Solution:**\nUse Chrome/Edge/Firefox (Safari limited support), check browser permissions, try different `displaySurface` values ('window', 'monitor', 'browser')\n\n### \"How do I schedule meetings?\"\n\n**Cause:** RealtimeKit has no built-in scheduling system\n**Solution:**\nStore meeting IDs in your database with timestamps. Generate participant tokens only when user should join. Example:\n```typescript\n// Store in DB\n{ meetingId: 'abc123', scheduledFor: '2026-02-15T10:00:00Z', userId: 'user456' }\n\n// Generate token when user clicks \"Join\" near scheduled time\nconst response = await fetch('/api/join-meeting', {\n method: 'POST',\n body: JSON.stringify({ meetingId: 'abc123' })\n});\nconst { authToken } = await response.json();\n```\n\n### \"Recording not starting\"\n\n**Cause:** Preset lacks recording permissions, no active session, or API call from client\n**Solution:**\nVerify preset has `canRecord: true` and `canStartStopRecording: true`, ensure session is active (at least one participant), make recording API calls server-side only\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Max participants per session | 100 |\n| Max concurrent sessions per App | 1000 |\n| Max recording duration | 6 hours |\n| Max meeting duration | 24 hours |\n| Max chat message length | 4000 characters |\n| Max preset name length | 64 characters |\n| Max meeting title length | 256 characters |\n| Max participant name length | 256 characters |\n| Token expiration | 24 hours (default) |\n| WebRTC ports required | UDP 1024-65535 |\n\n## Network Requirements\n\n### Firewall Rules\nAllow outbound UDP/TCP to:\n- `*.cloudflare.com` ports 443, 80\n- UDP ports 1024-65535 (WebRTC media)\n\n### TURN Service\nEnable for users behind restrictive firewalls/proxies:\n```jsonc\n// wrangler.jsonc\n{\n \"vars\": {\n \"TURN_SERVICE_ID\": \"your_turn_service_id\"\n }\n // Set secret: wrangler secret put TURN_SERVICE_TOKEN\n}\n```\n\nTURN automatically configured in SDK when enabled in account.\n\n## Debugging Tips\n\n```typescript\n// Check devices\nconst devices = await meeting.self.getAllDevices();\nmeeting.self.on('deviceListUpdate', ({ added, removed, devices }) => console.log('Devices:', { added, removed, devices }));\n\n// Monitor participants\nmeeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined:`, { id: p.id, userId: p.userId, audioEnabled: p.audioEnabled, videoEnabled: p.videoEnabled }));\n\n// Check room state\nmeeting.self.on('roomJoined', () => console.log('Room:', { meetingId: meeting.meta.meetingId, meetingTitle: meeting.meta.meetingTitle, participantCount: meeting.participants.joined.size() + 1, audioEnabled: meeting.self.audioEnabled, videoEnabled: meeting.self.videoEnabled }));\n\n// Log all events\n['roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'].forEach(event => meeting.self.on(event, (data) => console.log(`[self] ${event}:`, data)));\n['participantJoined', 'participantLeft'].forEach(event => meeting.participants.joined.on(event, (data) => console.log(`[participants] ${event}:`, data)));\nmeeting.chat.on('chatUpdate', (data) => console.log('[chat] chatUpdate:', data));\n```\n\n## Security & Performance\n\n### Security: Do NOT\n- Expose `CLOUDFLARE_API_TOKEN` in client code, hardcode credentials in frontend\n- Reuse participant tokens, store tokens in localStorage without encryption\n- Allow client-side meeting creation\n\n### Security: DO\n- Generate tokens server-side only, use HTTPS, implement rate limiting\n- Validate user auth before generating tokens, use `custom_participant_id` to map to your user system\n- Set appropriate preset permissions per user role, rotate API tokens regularly\n\n### Performance\n- **CPU**: Lower video resolution/frameRate, disable video for audio-only, use `meeting.participants.active` for large meetings, implement virtual scrolling\n- **Bandwidth**: Set max resolution in `mediaConfiguration`, disable screenshare audio if unneeded, use audio-only mode, implement adaptive bitrate\n- **Memory**: Clean up event listeners on unmount, call `meeting.leave()` when done, don't store large participant arrays\n\n## In This Reference\n- [README.md](README.md) - Overview, core concepts, quick start\n- [configuration.md](configuration.md) - SDK config, presets, wrangler setup\n- [api.md](api.md) - Client SDK APIs, REST endpoints\n- [patterns.md](patterns.md) - Common patterns, React hooks, backend integration\n" }, { "path": "skills/.curated/cloudflare-deploy/references/realtimekit/patterns.md", "content": "# RealtimeKit Patterns\n\n## UI Kit (Minimal Code)\n\n```tsx\n// React\nimport { RtkMeeting } from '@cloudflare/realtimekit-react-ui';\n\" onLeave={() => console.log('Left')} />\n\n// Angular\n@Component({ template: `` })\nexport class AppComponent { authToken = ''; onLeave(event: unknown) {} }\n\n// HTML/Web Components\n\n\n\n```\n\n## UI Components\n\nRealtimeKit provides 133+ pre-built Stencil.js Web Components with framework wrappers:\n\n### Layout Components\n- `` - Full meeting UI (all-in-one)\n- ``, ``, `` - Layout sections\n- `` - Chat/participants sidebar\n- `` - Adaptive video grid\n\n### Control Components \n- ``, `` - Media controls\n- `` - Screen sharing\n- `` - Leave meeting\n- `` - Device settings\n\n### Grid Variants\n- `` - Active speaker focus\n- `` - Audio-only mode\n- `` - Paginated layout\n\n**See full catalog**: https://docs.realtime.cloudflare.com/ui-kit\n\n## Core SDK Patterns\n\n### Basic Setup\n```typescript\nimport RealtimeKitClient from '@cloudflare/realtimekit';\n\nconst meeting = new RealtimeKitClient({ authToken, video: true, audio: true });\nmeeting.self.on('roomJoined', () => console.log('Joined:', meeting.meta.meetingTitle));\nmeeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined`));\nawait meeting.join();\n```\n\n### Video Grid & Device Selection\n```typescript\n// Video grid\nfunction VideoGrid({ meeting }) {\n const [participants, setParticipants] = useState([]);\n useEffect(() => {\n const update = () => setParticipants(meeting.participants.joined.toArray());\n meeting.participants.joined.on('participantJoined', update);\n meeting.participants.joined.on('participantLeft', update);\n update();\n return () => { meeting.participants.joined.off('participantJoined', update); meeting.participants.joined.off('participantLeft', update); };\n }, [meeting]);\n return
\n {participants.map(p => )}\n
;\n}\n\nfunction VideoTile({ participant }) {\n const videoRef = useRef(null);\n useEffect(() => {\n if (videoRef.current && participant.videoTrack) videoRef.current.srcObject = new MediaStream([participant.videoTrack]);\n }, [participant.videoTrack]);\n return
;\n}\n\n// Device selection\nconst devices = await meeting.self.getAllDevices();\nconst switchCamera = (deviceId: string) => {\n const device = devices.find(d => d.deviceId === deviceId);\n if (device) await meeting.self.setDevice(device);\n};\n```\n\n## React Hooks (Official)\n\n```typescript\nimport { useRealtimeKitClient, useRealtimeKitSelector } from '@cloudflare/realtimekit-react-ui';\n\nfunction MyComponent() {\n const [meeting, initMeeting] = useRealtimeKitClient();\n const audioEnabled = useRealtimeKitSelector(m => m.self.audioEnabled);\n const participantCount = useRealtimeKitSelector(m => m.participants.joined.size());\n \n useEffect(() => { initMeeting({ authToken: '' }); }, []);\n \n return
\n \n {participantCount} participants\n
;\n}\n```\n\n**Benefits:** Automatic re-renders, memoized selectors, type-safe\n\n## Waitlist Handling\n\n```typescript\n// Monitor waitlist\nmeeting.participants.waitlisted.on('participantJoined', (participant) => {\n console.log(`${participant.name} is waiting`);\n // Show admin UI to approve/reject\n});\n\n// Approve from waitlist (backend only)\nawait fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/realtime/kit/${appId}/meetings/${meetingId}/active-session/waitlist/approve`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}` },\n body: JSON.stringify({ user_ids: [participant.userId] })\n }\n);\n\n// Client receives automatic transition when approved\nmeeting.self.on('roomJoined', () => console.log('Approved and joined'));\n```\n\n## Audio-Only Mode\n\n```typescript\nconst meeting = new RealtimeKitClient({\n authToken: '',\n video: false, // Disable video\n audio: true,\n mediaConfiguration: {\n audio: {\n echoCancellation: true,\n noiseSuppression: true,\n autoGainControl: true\n }\n }\n});\n\n// Use audio grid component\nimport { RtkAudioGrid } from '@cloudflare/realtimekit-react-ui';\n\n```\n\n## Addon System\n\n```typescript\n// List available addons\nmeeting.plugins.all.forEach(plugin => {\n console.log(plugin.id, plugin.name, plugin.active);\n});\n\n// Activate collaborative app\nawait meeting.plugins.activate('whiteboard-addon-id');\n\n// Listen for activations\nmeeting.plugins.on('pluginActivated', ({ plugin }) => {\n console.log(`${plugin.name} activated`);\n});\n\n// Deactivate\nawait meeting.plugins.deactivate();\n```\n\n## Backend Integration\n\n### Token Generation (Workers)\n```typescript\nexport interface Env { CLOUDFLARE_API_TOKEN: string; CLOUDFLARE_ACCOUNT_ID: string; REALTIMEKIT_APP_ID: string; }\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n \n if (url.pathname === '/api/join-meeting') {\n const { meetingId, userName, presetName } = await request.json();\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/realtime/kit/${env.REALTIMEKIT_APP_ID}/meetings/${meetingId}/participants`,\n {\n method: 'POST',\n headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${env.CLOUDFLARE_API_TOKEN}` },\n body: JSON.stringify({ name: userName, preset_name: presetName })\n }\n );\n const data = await response.json();\n return Response.json({ authToken: data.result.authToken });\n }\n \n return new Response('Not found', { status: 404 });\n }\n};\n```\n\n## Best Practices\n\n### Security\n1. **Never expose API tokens client-side** - Generate participant tokens server-side only\n2. **Don't reuse participant tokens** - Generate fresh token per session, use refresh endpoint if expired\n3. **Use custom participant IDs** - Map to your user system for cross-session tracking\n\n### Performance\n1. **Event-driven updates** - Listen to events, don't poll. Use `toArray()` only when needed\n2. **Media quality constraints** - Set appropriate resolution/bitrate limits based on network conditions\n3. **Device management** - Enable `autoSwitchAudioDevice` for better UX, handle device list updates\n\n### Architecture\n1. **Separate Apps for environments** - staging vs production to prevent data mixing\n2. **Preset strategy** - Create presets at App level, reuse across meetings\n3. **Token management** - Backend generates tokens, frontend receives via authenticated endpoint\n\n## In This Reference\n- [README.md](README.md) - Overview, core concepts, quick start\n- [configuration.md](configuration.md) - SDK config, presets, wrangler setup\n- [api.md](api.md) - Client SDK APIs, REST endpoints\n- [gotchas.md](gotchas.md) - Common issues, troubleshooting, limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/sandbox/README.md", "content": "# Cloudflare Sandbox SDK\n\nSecure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.\n\n**Use cases**: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.\n\n## Architecture\n\n- Each sandbox = Durable Object + Container\n- Persistent across requests (same ID = same sandbox)\n- Isolated filesystem/processes/network\n- Configurable sleep/wake for cost optimization\n\n## Quick Start\n\n```typescript\nimport { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';\nexport { Sandbox } from '@cloudflare/sandbox';\n\ntype Env = { Sandbox: DurableObjectNamespace; };\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // CRITICAL: proxyToSandbox MUST be called first for preview URLs\n const proxyResponse = await proxyToSandbox(request, env);\n if (proxyResponse) return proxyResponse;\n\n const sandbox = getSandbox(env.Sandbox, 'my-sandbox');\n const result = await sandbox.exec('python3 -c \"print(2 + 2)\"');\n return Response.json({ output: result.stdout });\n }\n};\n```\n\n**wrangler.jsonc**:\n```jsonc\n{\n \"name\": \"my-sandbox-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \n \"containers\": [{\n \"class_name\": \"Sandbox\",\n \"image\": \"./Dockerfile\",\n \"instance_type\": \"lite\", // lite | standard | heavy\n \"max_instances\": 5\n }],\n \n \"durable_objects\": {\n \"bindings\": [{ \"class_name\": \"Sandbox\", \"name\": \"Sandbox\" }]\n },\n \n \"migrations\": [{\n \"tag\": \"v1\",\n \"new_sqlite_classes\": [\"Sandbox\"]\n }]\n}\n```\n\n**Dockerfile**:\n```dockerfile\nFROM docker.io/cloudflare/sandbox:latest\nRUN pip3 install --no-cache-dir pandas numpy matplotlib\nEXPOSE 8080 3000 # Required for wrangler dev\n```\n\n## Core APIs\n\n- `getSandbox(namespace, id, options?)` → Get/create sandbox\n- `sandbox.exec(command, options?)` → Execute command\n- `sandbox.readFile(path)` / `writeFile(path, content)` → File ops\n- `sandbox.startProcess(command, options)` → Background process\n- `sandbox.exposePort(port, options)` → Get preview URL\n- `sandbox.createSession(options)` → Isolated session\n- `sandbox.wsConnect(request, port)` → WebSocket proxy\n- `sandbox.destroy()` → Terminate container\n- `sandbox.mountBucket(bucket, path, options)` → Mount S3 storage\n\n## Critical Rules\n\n- ALWAYS call `proxyToSandbox()` first\n- Same ID = reuse sandbox\n- Use `/workspace` for persistent files\n- `normalizeId: true` for preview URLs\n- Retry on `CONTAINER_NOT_READY`\n\n## In This Reference\n- [configuration.md](./configuration.md) - Config, CLI, environment setup\n- [api.md](./api.md) - Programmatic API, testing patterns\n- [patterns.md](./patterns.md) - Common workflows, CI/CD integration\n- [gotchas.md](./gotchas.md) - Issues, limits, best practices\n\n## See Also\n- [durable-objects](../durable-objects/) - Sandbox runs on DO infrastructure\n- [containers](../containers/) - Container runtime fundamentals\n- [workers](../workers/) - Entry point for sandbox requests\n" }, { "path": "skills/.curated/cloudflare-deploy/references/sandbox/api.md", "content": "# API Reference\n\n## Command Execution\n\n```typescript\n// Basic\nconst result = await sandbox.exec('python3 script.py');\n// Returns: { stdout, stderr, exitCode, success, duration }\n\n// With options\nawait sandbox.exec('python3 test.py', {\n cwd: '/workspace/project',\n env: { API_KEY: 'secret' },\n stream: true,\n onOutput: (stream, data) => console.log(data)\n});\n```\n\n## File Operations\n\n```typescript\n// Read/Write\nconst { content } = await sandbox.readFile('/workspace/data.txt');\nawait sandbox.writeFile('/workspace/file.txt', 'content'); // Auto-creates dirs\n\n// List/Delete\nconst files = await sandbox.listFiles('/workspace');\nawait sandbox.deleteFile('/workspace/temp.txt');\nawait sandbox.deleteFile('/workspace/dir', { recursive: true });\n\n// Utils\nawait sandbox.mkdir('/workspace/dir', { recursive: true });\nawait sandbox.pathExists('/workspace/file.txt');\n```\n\n## Background Processes\n\n```typescript\n// Start\nconst process = await sandbox.startProcess('python3 -m http.server 8080', {\n processId: 'web-server',\n cwd: '/workspace/public',\n env: { PORT: '8080' }\n});\n// Returns: { id, pid, command }\n\n// Wait for readiness\nawait process.waitForPort(8080); // Wait for port to listen\nawait process.waitForLog(/Server running/); // Wait for log pattern\nawait process.waitForExit(); // Wait for completion\n\n// Management\nconst processes = await sandbox.listProcesses();\nconst info = await sandbox.getProcess('web-server');\nawait sandbox.stopProcess('web-server');\nconst logs = await sandbox.getProcessLogs('web-server');\n```\n\n## Port Exposure\n\n```typescript\n// Expose port\nconst { url } = await sandbox.exposePort(8080, {\n name: 'web-app',\n hostname: request.hostname\n});\n\n// Management\nawait sandbox.isPortExposed(8080);\nawait sandbox.getExposedPorts(request.hostname);\nawait sandbox.unexposePort(8080);\n```\n\n## Sessions (Isolated Contexts)\n\nEach session maintains own shell state, env vars, cwd, process namespace.\n\n```typescript\n// Create with context\nconst session = await sandbox.createSession({\n id: 'user-123',\n cwd: '/workspace/user123',\n env: { USER_ID: '123' }\n});\n\n// Use (full sandbox API)\nawait session.exec('echo $USER_ID');\nawait session.writeFile('config.txt', 'data');\n\n// Manage\nawait sandbox.getSession('user-123');\nawait sandbox.deleteSession('user-123');\n```\n\n## Code Interpreter\n\n```typescript\n// Create context with variables\nconst ctx = await sandbox.createCodeContext({\n language: 'python',\n variables: {\n data: [1, 2, 3, 4, 5],\n config: { verbose: true }\n }\n});\n\n// Execute code with rich outputs\nconst result = await ctx.runCode(`\nimport matplotlib.pyplot as plt\nplt.plot(data, [x**2 for x in data])\nplt.savefig('plot.png')\nprint(f\"Processed {len(data)} points\")\n`);\n// Returns: { outputs: [{ type: 'text'|'image'|'html', content }], error }\n\n// Context persists variables across runs\nconst result2 = await ctx.runCode('print(data[0])'); // Still has 'data'\n```\n\n## WebSocket Connections\n\n```typescript\n// Proxy WebSocket to sandbox service\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const proxyResponse = await proxyToSandbox(request, env);\n if (proxyResponse) return proxyResponse;\n\n if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {\n const sandbox = getSandbox(env.Sandbox, 'realtime');\n return await sandbox.wsConnect(request, 8080);\n }\n \n return new Response('Not a WebSocket request', { status: 400 });\n }\n};\n```\n\n## Bucket Mounting (S3 Storage)\n\n```typescript\n// Mount R2 bucket (production only, not wrangler dev)\nawait sandbox.mountBucket(env.DATA_BUCKET, '/data', {\n readOnly: false\n});\n\n// Access files in mounted bucket\nawait sandbox.exec('ls /data');\nawait sandbox.writeFile('/data/output.txt', 'result');\n\n// Unmount\nawait sandbox.unmountBucket('/data');\n```\n\n**Note**: Bucket mounting only works in production. Mounted buckets are sandbox-scoped (visible to all sessions in that sandbox).\n\n## Lifecycle Management\n\n```typescript\n// Terminate container immediately\nawait sandbox.destroy();\n\n// REQUIRED when using keepAlive: true\nconst sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });\ntry {\n await sandbox.writeFile('/tmp/code.py', code);\n const result = await sandbox.exec('python /tmp/code.py');\n return result.stdout;\n} finally {\n await sandbox.destroy(); // Free resources\n}\n```\n\nDeletes: files, processes, sessions, network connections, exposed ports.\n\n## Error Handling\n\n```typescript\n// Command errors\nconst result = await sandbox.exec('python3 invalid.py');\nif (!result.success) {\n console.error('Exit code:', result.exitCode);\n console.error('Stderr:', result.stderr);\n}\n\n// SDK errors\ntry {\n await sandbox.readFile('/nonexistent');\n} catch (error) {\n if (error.code === 'FILE_NOT_FOUND') { /* ... */ }\n else if (error.code === 'CONTAINER_NOT_READY') { /* retry */ }\n else if (error.code === 'TIMEOUT') { /* ... */ }\n}\n\n// Retry pattern (see gotchas.md for full implementation)\n```\n\n\n" }, { "path": "skills/.curated/cloudflare-deploy/references/sandbox/configuration.md", "content": "# Configuration\n\n## getSandbox Options\n\n```typescript\nconst sandbox = getSandbox(env.Sandbox, 'sandbox-id', {\n normalizeId: true, // lowercase ID (required for preview URLs)\n sleepAfter: '10m', // sleep after inactivity: '5m', '1h', '2d' (default: '10m')\n keepAlive: false, // false = auto-timeout, true = never sleep\n \n containerTimeouts: {\n instanceGetTimeoutMS: 30000, // 30s for provisioning (default: 30000)\n portReadyTimeoutMS: 90000 // 90s for container startup (default: 90000)\n }\n});\n```\n\n**Sleep Config**:\n- `sleepAfter`: Duration string (e.g., '5m', '10m', '1h') - default: '10m'\n- `keepAlive: false`: Auto-sleep (default, cost-optimized)\n- `keepAlive: true`: Never sleep (higher cost, requires explicit `destroy()`)\n- Sleeping sandboxes wake automatically (cold start)\n\n## Instance Types\n\nwrangler.jsonc `instance_type`:\n- `lite`: 256MB RAM, 0.5 vCPU (default)\n- `standard`: 512MB RAM, 1 vCPU\n- `heavy`: 1GB RAM, 2 vCPU\n\n## Dockerfile Patterns\n\n**Basic**:\n```dockerfile\nFROM docker.io/cloudflare/sandbox:latest\nRUN pip3 install --no-cache-dir pandas numpy\nEXPOSE 8080 # Required for wrangler dev\n```\n\n**Scientific**:\n```dockerfile\nFROM docker.io/cloudflare/sandbox:latest\nRUN pip3 install --no-cache-dir \\\n jupyter-server ipykernel matplotlib \\\n pandas seaborn plotly scipy scikit-learn\n```\n\n**Node.js**:\n```dockerfile\nFROM docker.io/cloudflare/sandbox:latest\nRUN npm install -g typescript ts-node\n```\n\n**CRITICAL**: `EXPOSE` required for `wrangler dev` port access. Production auto-exposes all ports.\n\n## CLI Commands\n\n```bash\n# Dev\nwrangler dev # Start local dev server\nwrangler deploy # Deploy to production\nwrangler tail # Monitor logs\nwrangler containers list # Check container status\nwrangler secret put KEY # Set secret\n```\n\n## Environment & Secrets\n\n**wrangler.jsonc**:\n```jsonc\n{\n \"vars\": {\n \"ENVIRONMENT\": \"production\",\n \"API_URL\": \"https://api.example.com\"\n },\n \"r2_buckets\": [{\n \"binding\": \"DATA_BUCKET\",\n \"bucket_name\": \"my-data-bucket\"\n }]\n}\n```\n\n**Usage**:\n```typescript\nconst token = env.GITHUB_TOKEN; // From wrangler secret\nawait sandbox.exec('git clone ...', {\n env: { GIT_TOKEN: token }\n});\n```\n\n## Preview URL Setup\n\n**Prerequisites**:\n- Custom domain with wildcard DNS: `*.yourdomain.com → worker.yourdomain.com`\n- `.workers.dev` domains NOT supported\n- `normalizeId: true` in getSandbox\n- `proxyToSandbox()` called first in fetch handler\n\n## Cron Triggers (Pre-warming)\n\n```jsonc\n{\n \"triggers\": {\n \"crons\": [\"*/5 * * * *\"] // Every 5 minutes\n }\n}\n```\n\n```typescript\nexport default {\n async scheduled(event: ScheduledEvent, env: Env) {\n const sandbox = getSandbox(env.Sandbox, 'main');\n await sandbox.exec('echo \"keepalive\"'); // Wake sandbox\n }\n};\n```\n\n## Logging Configuration\n\n**wrangler.jsonc**:\n```jsonc\n{\n \"vars\": {\n \"SANDBOX_LOG_LEVEL\": \"debug\", // debug | info | warn | error (default: info)\n \"SANDBOX_LOG_FORMAT\": \"pretty\" // json | pretty (default: json)\n }\n}\n```\n\n**Dev**: `debug` + `pretty`. **Production**: `info`/`warn` + `json`.\n\n## Timeout Environment Overrides\n\nOverride default timeouts via environment variables:\n\n```jsonc\n{\n \"vars\": {\n \"SANDBOX_INSTANCE_TIMEOUT_MS\": \"60000\", // Override instanceGetTimeoutMS\n \"SANDBOX_PORT_TIMEOUT_MS\": \"120000\" // Override portReadyTimeoutMS\n }\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/sandbox/gotchas.md", "content": "# Gotchas & Best Practices\n\n## Common Errors\n\n### \"Container running indefinitely\"\n\n**Cause:** `keepAlive: true` without calling `destroy()`\n**Solution:** Always call `destroy()` when done with keepAlive containers\n\n```typescript\nconst sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });\ntry {\n const result = await sandbox.exec('python script.py');\n return result.stdout;\n} finally {\n await sandbox.destroy(); // REQUIRED to free resources\n}\n```\n\n### \"CONTAINER_NOT_READY\"\n\n**Cause:** Container still provisioning (first request or after sleep)\n**Solution:** Retry after 2-3s\n\n```typescript\nasync function execWithRetry(sandbox, cmd) {\n for (let i = 0; i < 3; i++) {\n try {\n return await sandbox.exec(cmd);\n } catch (e) {\n if (e.code === 'CONTAINER_NOT_READY') {\n await new Promise(r => setTimeout(r, 2000));\n continue;\n }\n throw e;\n }\n }\n}\n```\n\n### \"Connection refused: container port not found\"\n\n**Cause:** Missing `EXPOSE` directive in Dockerfile\n**Solution:** Add `EXPOSE ` to Dockerfile (only needed for `wrangler dev`, production auto-exposes)\n\n### \"Preview URLs not working\"\n\n**Cause:** Custom domain not configured, wildcard DNS missing, `normalizeId` not set, or `proxyToSandbox()` not called\n**Solution:** Check:\n1. Custom domain configured? (not `.workers.dev`)\n2. Wildcard DNS set up? (`*.domain.com → worker.domain.com`)\n3. `normalizeId: true` in getSandbox?\n4. `proxyToSandbox()` called first in fetch?\n\n### \"Slow first request\"\n\n**Cause:** Cold start (container provisioning)\n**Solution:**\n- Use `sleepAfter` instead of creating new sandboxes\n- Pre-warm with cron triggers\n- Set `keepAlive: true` for critical sandboxes\n\n### \"File not persisting\"\n\n**Cause:** Files in `/tmp` or other ephemeral paths\n**Solution:** Use `/workspace` for persistent files\n\n### \"Bucket mounting doesn't work locally\"\n\n**Cause:** Bucket mounting requires FUSE, not available in `wrangler dev`\n**Solution:** Test bucket mounting in production only. Use mock data locally.\n\n### \"Different normalizeId = different sandbox\"\n\n**Cause:** Changing `normalizeId` option changes Durable Object ID\n**Solution:** Set `normalizeId` consistently. `normalizeId: true` lowercases the ID.\n\n```typescript\n// These create DIFFERENT sandboxes:\ngetSandbox(env.Sandbox, 'MyApp'); // DO ID: hash('MyApp')\ngetSandbox(env.Sandbox, 'MyApp', { normalizeId: true }); // DO ID: hash('myapp')\n```\n\n### \"Code context variables disappeared\"\n\n**Cause:** Container restart clears code context state\n**Solution:** Code contexts are ephemeral. Recreate context after container sleep/wake.\n\n## Performance Optimization\n\n### Sandbox ID Strategy\n\n```typescript\n// ❌ BAD: New sandbox every time (slow)\nconst sandbox = getSandbox(env.Sandbox, `user-${Date.now()}`);\n\n// ✅ GOOD: Reuse per user\nconst sandbox = getSandbox(env.Sandbox, `user-${userId}`);\n```\n\n### Sleep & Traffic Config\n\n```typescript\n// Cost-optimized\ngetSandbox(env.Sandbox, 'id', { sleepAfter: '30m', keepAlive: false });\n\n// Always-on (requires destroy())\ngetSandbox(env.Sandbox, 'id', { keepAlive: true });\n```\n\n```jsonc\n// High traffic: increase max_instances\n{ \"containers\": [{ \"class_name\": \"Sandbox\", \"max_instances\": 50 }] }\n```\n\n## Security Best Practices\n\n### Sandbox Isolation\n- Each sandbox = isolated container (filesystem, network, processes)\n- Use unique sandbox IDs per tenant for multi-tenant apps\n- Sandboxes cannot communicate directly\n\n### Input Validation\n\n```typescript\n// ❌ DANGEROUS: Command injection\nconst result = await sandbox.exec(`python3 -c \"${userCode}\"`);\n\n// ✅ SAFE: Write to file, execute file\nawait sandbox.writeFile('/workspace/user_code.py', userCode);\nconst result = await sandbox.exec('python3 /workspace/user_code.py');\n```\n\n### Resource Limits\n\n```typescript\n// Timeout long-running commands\nconst result = await sandbox.exec('python3 script.py', {\n timeout: 30000 // 30 seconds\n});\n```\n\n### Secrets Management\n\n```typescript\n// ❌ NEVER hardcode secrets\nconst token = 'ghp_abc123';\n\n// ✅ Use environment secrets\nconst token = env.GITHUB_TOKEN;\n\n// Pass to sandbox via exec env\nconst result = await sandbox.exec('git clone ...', {\n env: { GIT_TOKEN: token }\n});\n```\n\n### Preview URL Security\nPreview URLs include auto-generated tokens:\n```\nhttps://8080-sandbox-abc123def456.yourdomain.com\n```\nToken changes on each expose operation, preventing unauthorized access.\n\n## Limits\n\n| Resource | Lite | Standard | Heavy |\n|----------|------|----------|-------|\n| RAM | 256MB | 512MB | 1GB |\n| vCPU | 0.5 | 1 | 2 |\n\n| Operation | Default Timeout | Override |\n|-----------|----------------|----------|\n| Container provisioning | 30s | `SANDBOX_INSTANCE_TIMEOUT_MS` |\n| Port readiness | 90s | `SANDBOX_PORT_TIMEOUT_MS` |\n| exec() | 120s | `timeout` option |\n| sleepAfter | 10m | `sleepAfter` option |\n\n**Performance**:\n- **First deploy**: 2-3 min for container build\n- **Cold start**: 2-3s when waking from sleep\n- **Bucket mounting**: Production only (FUSE not in dev)\n\n## Production Guide\n\nSee: https://developers.cloudflare.com/sandbox/guides/production-deployment/\n\n## Resources\n\n- [Official Docs](https://developers.cloudflare.com/sandbox/)\n- [API Reference](https://developers.cloudflare.com/sandbox/api/)\n- [Examples](https://github.com/cloudflare/sandbox-sdk/tree/main/examples)\n- [npm Package](https://www.npmjs.com/package/@cloudflare/sandbox)\n- [Discord Support](https://discord.cloudflare.com)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/sandbox/patterns.md", "content": "# Common Patterns\n\n## AI Code Execution with Code Context\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const { code, variables } = await request.json();\n const sandbox = getSandbox(env.Sandbox, 'ai-agent');\n \n // Create context with persistent variables\n const ctx = await sandbox.createCodeContext({\n language: 'python',\n variables: variables || {}\n });\n \n // Execute with rich outputs (text, images, HTML)\n const result = await ctx.runCode(code);\n \n return Response.json({\n outputs: result.outputs, // [{ type: 'text'|'image'|'html', content }]\n error: result.error,\n success: !result.error\n });\n }\n};\n```\n\n## Interactive Dev Environment\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const proxyResponse = await proxyToSandbox(request, env);\n if (proxyResponse) return proxyResponse;\n \n const sandbox = getSandbox(env.Sandbox, 'ide', { normalizeId: true });\n \n if (request.url.endsWith('/start')) {\n await sandbox.exec('curl -fsSL https://code-server.dev/install.sh | sh');\n await sandbox.startProcess('code-server --bind-addr 0.0.0.0:8080', {\n processId: 'vscode'\n });\n \n const exposed = await sandbox.exposePort(8080);\n return Response.json({ url: exposed.url });\n }\n \n return new Response('Try /start');\n }\n};\n```\n\n## WebSocket Real-Time Service\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const proxyResponse = await proxyToSandbox(request, env);\n if (proxyResponse) return proxyResponse;\n\n if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {\n const sandbox = getSandbox(env.Sandbox, 'realtime-service');\n return await sandbox.wsConnect(request, 8080);\n }\n\n // Non-WebSocket: expose preview URL\n const sandbox = getSandbox(env.Sandbox, 'realtime-service');\n const { url } = await sandbox.exposePort(8080, {\n hostname: new URL(request.url).hostname\n });\n return Response.json({ wsUrl: url.replace('https', 'wss') });\n }\n};\n```\n\n**Dockerfile**:\n```dockerfile\nFROM docker.io/cloudflare/sandbox:latest\nRUN npm install -g ws\nEXPOSE 8080\n```\n\n## Process Readiness Pattern\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const sandbox = getSandbox(env.Sandbox, 'app-server');\n \n // Start server\n const process = await sandbox.startProcess(\n 'node server.js',\n { processId: 'server' }\n );\n \n // Wait for server to be ready\n await process.waitForPort(8080); // Wait for port listening\n \n // Now safe to expose\n const { url } = await sandbox.exposePort(8080);\n return Response.json({ url });\n }\n};\n```\n\n## Persistent Data with Bucket Mounting\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const sandbox = getSandbox(env.Sandbox, 'data-processor');\n \n // Mount R2 bucket (production only)\n await sandbox.mountBucket(env.DATA_BUCKET, '/data', {\n readOnly: false\n });\n \n // Process files in bucket\n const result = await sandbox.exec('python3 /workspace/process.py', {\n env: { DATA_DIR: '/data/input' }\n });\n \n // Results written to /data/output are persisted in R2\n return Response.json({ success: result.success });\n }\n};\n```\n\n## CI/CD Pipeline\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const { repo, branch } = await request.json();\n const sandbox = getSandbox(env.Sandbox, `ci-${repo}-${Date.now()}`);\n \n await sandbox.exec(`git clone -b ${branch} ${repo} /workspace/repo`);\n \n const install = await sandbox.exec('npm install', {\n cwd: '/workspace/repo',\n stream: true,\n onOutput: (stream, data) => console.log(data)\n });\n \n if (!install.success) {\n return Response.json({ success: false, error: 'Install failed' });\n }\n \n const test = await sandbox.exec('npm test', { cwd: '/workspace/repo' });\n \n return Response.json({\n success: test.success,\n output: test.stdout,\n exitCode: test.exitCode\n });\n }\n};\n```\n\n\n\n\n\n## Multi-Tenant Pattern\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const userId = request.headers.get('X-User-ID');\n const sandbox = getSandbox(env.Sandbox, 'multi-tenant');\n \n // Each user gets isolated session\n let session;\n try {\n session = await sandbox.getSession(userId);\n } catch {\n session = await sandbox.createSession({\n id: userId,\n cwd: `/workspace/users/${userId}`,\n env: { USER_ID: userId }\n });\n }\n \n const code = await request.text();\n const result = await session.exec(`python3 -c \"${code}\"`);\n \n return Response.json({ output: result.stdout });\n }\n};\n```\n\n## Git Operations\n\n```typescript\n// Clone repo\nawait sandbox.exec('git clone https://github.com/user/repo.git /workspace/repo');\n\n// Authenticated (use env secrets)\nawait sandbox.exec(`git clone https://${env.GITHUB_TOKEN}@github.com/user/repo.git`);\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/secrets-store/README.md", "content": "# Cloudflare Secrets Store\n\nAccount-level encrypted secret management for Workers and AI Gateway.\n\n## Overview\n\n**Secrets Store**: Centralized, account-level secrets, reusable across Workers\n**Worker Secrets**: Per-Worker secrets (`wrangler secret put`)\n\n### Architecture\n\n- **Store**: Container (1/account in beta)\n- **Secret**: String ≤1024 bytes\n- **Scopes**: Permission boundaries controlling access\n - `workers`: For Workers runtime access\n - `ai-gateway`: For AI Gateway access\n - Secrets must have correct scope for binding to work\n- **Bindings**: Connect secrets via `env` object\n\n**Regional Availability**: Global except China Network (unavailable)\n\n### Access Control\n\n- **Super Admin**: Full access\n- **Admin**: Create/edit/delete secrets, view metadata\n- **Deployer**: View metadata + bindings\n- **Reporter**: View metadata only\n\nAPI Token permissions: `Account Secrets Store Edit/Read`\n\n### Limits (Beta)\n\n- 100 secrets/account\n- 1 store/account\n- 1024 bytes max/secret\n- Production secrets count toward limit\n\n## When to Use\n\n**Use Secrets Store when:**\n- Multiple Workers share same credential\n- Centralized management needed\n- Compliance requires audit trail\n- Team collaboration on secrets\n\n**Use Worker Secrets when:**\n- Secret unique to one Worker\n- Simple single-Worker project\n- No cross-Worker sharing needed\n\n## In This Reference\n\n### Reading Order by Task\n\n| Task | Start Here | Then Read |\n|------|------------|-----------|\n| Quick overview | README.md | - |\n| First-time setup | README.md → configuration.md | api.md |\n| Add secret to Worker | configuration.md | api.md |\n| Implement access pattern | api.md | patterns.md |\n| Debug errors | gotchas.md | api.md |\n| Secret rotation | patterns.md | configuration.md |\n| Best practices | gotchas.md | patterns.md |\n\n### Files\n\n- [configuration.md](./configuration.md) - Wrangler commands, binding config\n- [api.md](./api.md) - Binding API, get/put/delete operations\n- [patterns.md](./patterns.md) - Rotation, encryption, access control\n- [gotchas.md](./gotchas.md) - Security issues, limits, best practices\n\n## See Also\n- [workers](../workers/) - Worker bindings integration\n- [wrangler](../wrangler/) - CLI secret management commands\n" }, { "path": "skills/.curated/cloudflare-deploy/references/secrets-store/api.md", "content": "# API Reference\n\n## Binding API\n\n### Basic Access\n\n**CRITICAL**: Async `.get()` required - secrets NOT directly available.\n\n**`.get()` throws on error** - does NOT return null. Always use try/catch.\n\n```typescript\ninterface Env {\n API_KEY: { get(): Promise };\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const apiKey = await env.API_KEY.get();\n return fetch(\"https://api.example.com\", {\n headers: { \"Authorization\": `Bearer ${apiKey}` }\n });\n }\n}\n```\n\n### Error Handling\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n try {\n const apiKey = await env.API_KEY.get();\n return fetch(\"https://api.example.com\", {\n headers: { \"Authorization\": `Bearer ${apiKey}` }\n });\n } catch (error) {\n console.error(\"Secret access failed:\", error);\n return new Response(\"Configuration error\", { status: 500 });\n }\n }\n}\n```\n\n### Multiple Secrets & Patterns\n\n```typescript\n// Parallel fetch\nconst [stripeKey, sendgridKey] = await Promise.all([\n env.STRIPE_KEY.get(),\n env.SENDGRID_KEY.get()\n]);\n\n// ❌ Missing .get()\nconst key = env.API_KEY;\n\n// ❌ Module-level cache\nconst CACHED_KEY = await env.API_KEY.get(); // Fails\n\n// ✅ Request-scope cache\nconst key = await env.API_KEY.get(); // OK - reuse within request\n```\n\n## REST API\n\nBase: `https://api.cloudflare.com/client/v4`\n\n### Auth\n\n```bash\ncurl -H \"Authorization: Bearer $CF_TOKEN\" \\\n https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores\n```\n\n### Store Operations\n\n```bash\n# List\nGET /accounts/{account_id}/secrets_store/stores\n\n# Create\nPOST /accounts/{account_id}/secrets_store/stores\n{\"name\": \"my-store\"}\n\n# Delete\nDELETE /accounts/{account_id}/secrets_store/stores/{store_id}\n```\n\n### Secret Operations\n\n```bash\n# List\nGET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets\n\n# Create (single)\nPOST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets\n{\n \"name\": \"my_secret\",\n \"value\": \"secret_value\",\n \"scopes\": [\"workers\"],\n \"comment\": \"Optional\"\n}\n\n# Create (batch)\nPOST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets\n[\n {\"name\": \"secret_one\", \"value\": \"val1\", \"scopes\": [\"workers\"]},\n {\"name\": \"secret_two\", \"value\": \"val2\", \"scopes\": [\"workers\", \"ai-gateway\"]}\n]\n\n# Get metadata\nGET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}\n\n# Update\nPATCH /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}\n{\"value\": \"new_value\", \"comment\": \"Updated\"}\n\n# Delete (single)\nDELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}\n\n# Delete (batch)\nDELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets\n{\"secret_ids\": [\"id-1\", \"id-2\"]}\n\n# Duplicate\nPOST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}/duplicate\n{\"name\": \"new_name\"}\n\n# Quota\nGET /accounts/{account_id}/secrets_store/quota\n```\n\n### Responses\n\nSuccess:\n```json\n{\n \"success\": true,\n \"result\": {\n \"id\": \"secret-id-123\",\n \"name\": \"my_secret\",\n \"created\": \"2025-01-11T12:00:00Z\",\n \"scopes\": [\"workers\"]\n }\n}\n```\n\nError:\n```json\n{\n \"success\": false,\n \"errors\": [{\"code\": 10000, \"message\": \"Name exists\"}]\n}\n```\n\n## TypeScript Helpers\n\nOfficial types available via `@cloudflare/workers-types`:\n\n```typescript\nimport type { SecretsStoreSecret } from \"@cloudflare/workers-types\";\n\ninterface Env {\n STRIPE_API_KEY: SecretsStoreSecret;\n DATABASE_URL: SecretsStoreSecret;\n WORKER_SECRET: string; // Regular Worker secret (direct access)\n}\n```\n\nCustom helper type:\n\n```typescript\ninterface SecretsStoreBinding {\n get(): Promise;\n}\n\n// Fallback helper\nasync function getSecretWithFallback(\n primary: SecretsStoreBinding,\n fallback?: SecretsStoreBinding\n): Promise {\n try {\n return await primary.get();\n } catch (error) {\n if (fallback) return await fallback.get();\n throw error;\n }\n}\n\n// Batch helper\nasync function getAllSecrets(\n secrets: Record\n): Promise> {\n const entries = await Promise.all(\n Object.entries(secrets).map(async ([k, v]) => [k, await v.get()])\n );\n return Object.fromEntries(entries);\n}\n```\n\nSee: [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/secrets-store/configuration.md", "content": "# Configuration\n\n## Wrangler Config\n\n### Basic Binding\n\n**wrangler.jsonc**:\n\n```jsonc\n{\n \"secrets_store_secrets\": [\n {\n \"binding\": \"API_KEY\",\n \"store_id\": \"abc123\",\n \"secret_name\": \"stripe_api_key\"\n }\n ]\n}\n```\n\n**wrangler.toml** (alternative):\n\n```toml\n[[secrets_store_secrets]]\nbinding = \"API_KEY\"\nstore_id = \"abc123\"\nsecret_name = \"stripe_api_key\"\n```\n\nFields:\n- `binding`: Variable name for `env` access\n- `store_id`: From `wrangler secrets-store store list`\n- `secret_name`: Identifier (no spaces)\n\n### Environment-Specific\n\n**wrangler.jsonc**:\n\n```jsonc\n{\n \"env\": {\n \"production\": {\n \"secrets_store_secrets\": [\n {\n \"binding\": \"API_KEY\",\n \"store_id\": \"prod-store\",\n \"secret_name\": \"prod_api_key\"\n }\n ]\n },\n \"staging\": {\n \"secrets_store_secrets\": [\n {\n \"binding\": \"API_KEY\",\n \"store_id\": \"staging-store\",\n \"secret_name\": \"staging_api_key\"\n }\n ]\n }\n }\n}\n```\n\n**wrangler.toml** (alternative):\n\n```toml\n[env.production]\n[[env.production.secrets_store_secrets]]\nbinding = \"API_KEY\"\nstore_id = \"prod-store\"\nsecret_name = \"prod_api_key\"\n\n[env.staging]\n[[env.staging.secrets_store_secrets]]\nbinding = \"API_KEY\"\nstore_id = \"staging-store\"\nsecret_name = \"staging_api_key\"\n```\n\n## Wrangler Commands\n\n### Store Management\n\n```bash\nwrangler secrets-store store list\nwrangler secrets-store store create my-store --remote\nwrangler secrets-store store delete --remote\n```\n\n### Secret Management (Production)\n\n```bash\n# Create (interactive)\nwrangler secrets-store secret create \\\n --name MY_SECRET --scopes workers --remote\n\n# Create (piped)\ncat secret.txt | wrangler secrets-store secret create \\\n --name MY_SECRET --scopes workers --remote\n\n# List/get/update/delete\nwrangler secrets-store secret list --remote\nwrangler secrets-store secret get --name MY_SECRET --remote\nwrangler secrets-store secret update --name MY_SECRET --new-value \"val\" --remote\nwrangler secrets-store secret delete --name MY_SECRET --remote\n\n# Duplicate\nwrangler secrets-store secret duplicate \\\n --name ORIG --new-name COPY --remote\n```\n\n### Local Development\n\n**CRITICAL**: Production secrets (`--remote`) NOT accessible in local dev.\n\n```bash\n# Create local-only (no --remote)\nwrangler secrets-store secret create --name DEV_KEY --scopes workers\n\nwrangler dev # Uses local secrets\nwrangler deploy # Uses production secrets\n```\n\nBest practice: Separate names for local/prod:\n\n```jsonc\n{\n \"env\": {\n \"development\": {\n \"secrets_store_secrets\": [\n { \"binding\": \"API_KEY\", \"store_id\": \"store\", \"secret_name\": \"dev_api_key\" }\n ]\n },\n \"production\": {\n \"secrets_store_secrets\": [\n { \"binding\": \"API_KEY\", \"store_id\": \"store\", \"secret_name\": \"prod_api_key\" }\n ]\n }\n }\n}\n```\n\n## Dashboard\n\n### Creating Secrets\n\n1. **Secrets Store** → **Create secret**\n2. Fill: Name (no spaces), Value, Scope (`Workers`), Comment\n3. **Save** (value hidden after)\n\n### Adding Bindings\n\n**Method 1**: Worker → Settings → Bindings → Add → Secrets Store\n**Method 2**: Create secret directly from Worker settings dropdown\n\nDeploy options:\n- **Deploy**: Immediate 100%\n- **Save version**: Gradual rollout\n\n## CI/CD\n\n### GitHub Actions\n\n```yaml\n- name: Create secret\n env:\n CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}\n run: |\n echo \"${{ secrets.API_KEY }}\" | \\\n npx wrangler secrets-store secret create $STORE_ID \\\n --name API_KEY --scopes workers --remote\n\n- name: Deploy\n run: npx wrangler deploy\n```\n\n### GitLab CI\n\n```yaml\nscript:\n - echo \"$API_KEY_VALUE\" | npx wrangler secrets-store secret create $STORE_ID --name API_KEY --scopes workers --remote\n - npx wrangler deploy\n```\n\nSee: [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/secrets-store/gotchas.md", "content": "# Gotchas\n\n## Common Errors\n\n### \".get() Throws on Error\"\n\n**Cause:** Assuming `.get()` returns null on failure instead of throwing \n**Solution:** Always wrap `.get()` calls in try/catch blocks to handle errors gracefully\n\n```typescript\ntry {\n const key = await env.API_KEY.get();\n} catch (error) {\n return new Response(\"Configuration error\", { status: 500 });\n}\n```\n\n### \"Logging Secret Values\"\n\n**Cause:** Accidentally logging secret values in console or error messages \n**Solution:** Only log metadata (e.g., \"Retrieved API_KEY\") never the actual secret value\n\n### \"Module-Level Secret Access\"\n\n**Cause:** Attempting to access secrets during module initialization before env is available \n**Solution:** Cache secrets in request scope only, not at module level\n\n### \"Secret not found in store\"\n\n**Cause:** Secret name doesn't exist, case mismatch, missing workers scope, or incorrect store_id \n**Solution:** Verify secret exists with `wrangler secrets-store secret list --remote`, check name matches exactly (case-sensitive), ensure secret has `workers` scope, and verify correct store_id\n\n### \"Scope Mismatch\"\n\n**Cause:** Secret exists but missing `workers` scope (only has `ai-gateway` scope) \n**Solution:** Update secret scopes: `wrangler secrets-store secret update --name SECRET --scopes workers --remote` or add via Dashboard\n\n### \"JSON Parsing Failure\"\n\n**Cause:** Storing invalid JSON in secret, then failing to parse during runtime \n**Solution:** Validate JSON before storing:\n\n```bash\n# Validate before storing\necho '{\"key\":\"value\"}' | jq . && \\\n echo '{\"key\":\"value\"}' | wrangler secrets-store secret create \\\n --name CONFIG --scopes workers --remote\n```\n\nRuntime parsing with error handling:\n\n```typescript\ntry {\n const configStr = await env.CONFIG.get();\n const config = JSON.parse(configStr);\n} catch (error) {\n console.error(\"Invalid config JSON:\", error);\n return new Response(\"Invalid configuration\", { status: 500 });\n}\n```\n\n### \"Cannot access secret in local dev\"\n\n**Cause:** Attempting to access production secrets in local development environment \n**Solution:** Create local-only secrets (without `--remote` flag) for development: `wrangler secrets-store secret create --name API_KEY --scopes workers`\n\n### \"Property 'get' does not exist\"\n\n**Cause:** Missing TypeScript type definition for secret binding \n**Solution:** Define interface with get method: `interface Env { API_KEY: { get(): Promise }; }`\n\n### \"Binding already exists\"\n\n**Cause:** Duplicate binding in dashboard or conflict between wrangler.jsonc and dashboard \n**Solution:** Remove duplicate from dashboard Settings → Bindings, check for conflicts, or delete old Worker secret with `wrangler secret delete API_KEY`\n\n### \"Account secret quota exceeded\"\n\n**Cause:** Account has reached 100 secret limit (beta) \n**Solution:** Check quota with `wrangler secrets-store quota --remote`, delete unused secrets, consolidate duplicates, or contact Cloudflare for increase\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Max secrets per account | 100 | Beta limit |\n| Max stores per account | 1 | Beta limit |\n| Max secret size | 1024 bytes | Per secret |\n| Local secrets | Don't count toward limit | Only production secrets count |\n| Scopes available | `workers`, `ai-gateway` | Must have correct scope for access |\n| Scope | Account-level | Can be reused across multiple Workers |\n| Access method | `await env.BINDING.get()` | Async only, throws on error |\n| Management | Centralized | Via secrets-store commands |\n| Local dev | Separate local secrets | Use without `--remote` flag |\n| Regional availability | Global except China Network | Unavailable in China Network |\n\nSee: [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/secrets-store/patterns.md", "content": "# Patterns\n\n## Secret Rotation\n\nZero-downtime rotation with versioned naming (`api_key_v1`, `api_key_v2`):\n\n```typescript\ninterface Env {\n PRIMARY_KEY: { get(): Promise };\n FALLBACK_KEY?: { get(): Promise };\n}\n\nasync function fetchWithAuth(url: string, key: string) {\n return fetch(url, { headers: { \"Authorization\": `Bearer ${key}` } });\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n let resp = await fetchWithAuth(\"https://api.example.com\", await env.PRIMARY_KEY.get());\n \n // Fallback during rotation\n if (!resp.ok && env.FALLBACK_KEY) {\n resp = await fetchWithAuth(\"https://api.example.com\", await env.FALLBACK_KEY.get());\n }\n \n return resp;\n }\n}\n```\n\nWorkflow: Create `api_key_v2` → add fallback binding → deploy → swap primary → deploy → remove `v1`\n\n## Encryption with KV\n\n```typescript\ninterface Env {\n CACHE: KVNamespace;\n ENCRYPTION_KEY: { get(): Promise };\n}\n\nasync function encryptValue(value: string, key: string): Promise {\n const enc = new TextEncoder();\n const keyMaterial = await crypto.subtle.importKey(\n \"raw\", enc.encode(key), { name: \"AES-GCM\" }, false, [\"encrypt\"]\n );\n const iv = crypto.getRandomValues(new Uint8Array(12));\n const encrypted = await crypto.subtle.encrypt(\n { name: \"AES-GCM\", iv }, keyMaterial, enc.encode(value)\n );\n \n const combined = new Uint8Array(iv.length + encrypted.byteLength);\n combined.set(iv);\n combined.set(new Uint8Array(encrypted), iv.length);\n return btoa(String.fromCharCode(...combined));\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const key = await env.ENCRYPTION_KEY.get();\n const encrypted = await encryptValue(\"sensitive-data\", key);\n await env.CACHE.put(\"user:123:data\", encrypted);\n return Response.json({ ok: true });\n }\n}\n```\n\n## HMAC Signing\n\n```typescript\ninterface Env {\n HMAC_SECRET: { get(): Promise };\n}\n\nasync function signRequest(data: string, secret: string): Promise {\n const enc = new TextEncoder();\n const key = await crypto.subtle.importKey(\n \"raw\", enc.encode(secret), { name: \"HMAC\", hash: \"SHA-256\" }, false, [\"sign\"]\n );\n const sig = await crypto.subtle.sign(\"HMAC\", key, enc.encode(data));\n return btoa(String.fromCharCode(...new Uint8Array(sig)));\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const secret = await env.HMAC_SECRET.get();\n const payload = await request.text();\n const signature = await signRequest(payload, secret);\n return Response.json({ signature });\n }\n}\n```\n\n## Audit & Monitoring\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext) {\n const startTime = Date.now();\n try {\n const apiKey = await env.API_KEY.get();\n const resp = await fetch(\"https://api.example.com\", {\n headers: { \"Authorization\": `Bearer ${apiKey}` }\n });\n \n ctx.waitUntil(\n fetch(\"https://log.example.com/log\", {\n method: \"POST\",\n body: JSON.stringify({\n event: \"secret_used\",\n secret_name: \"API_KEY\",\n timestamp: new Date().toISOString(),\n duration_ms: Date.now() - startTime,\n success: resp.ok\n })\n })\n );\n return resp;\n } catch (error) {\n ctx.waitUntil(\n fetch(\"https://log.example.com/log\", {\n method: \"POST\",\n body: JSON.stringify({\n event: \"secret_access_failed\",\n secret_name: \"API_KEY\",\n error: error instanceof Error ? error.message : \"Unknown\"\n })\n })\n );\n return new Response(\"Error\", { status: 500 });\n }\n }\n}\n```\n\n## Migration from Worker Secrets\n\nChange `env.SECRET` (direct) to `await env.SECRET.get()` (async).\n\nSteps:\n1. Create in Secrets Store: `wrangler secrets-store secret create --name API_KEY --scopes workers --remote`\n2. Add binding to `wrangler.jsonc`: `{\"binding\": \"API_KEY\", \"store_id\": \"abc123\", \"secret_name\": \"api_key\"}`\n3. Update code: `const key = await env.API_KEY.get();`\n4. Test staging, deploy\n5. Remove old: `wrangler secret delete API_KEY`\n\n## Sharing Across Workers\n\nSame secret, different binding names:\n\n```jsonc\n// worker-1: binding=\"SHARED_DB\", secret_name=\"postgres_url\"\n// worker-2: binding=\"DB_CONN\", secret_name=\"postgres_url\"\n```\n\n## JSON Secret Parsing\n\nStore structured config as JSON secrets:\n\n```typescript\ninterface Env {\n DB_CONFIG: { get(): Promise };\n}\n\ninterface DbConfig {\n host: string;\n port: number;\n username: string;\n password: string;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n try {\n const configStr = await env.DB_CONFIG.get();\n const config: DbConfig = JSON.parse(configStr);\n \n // Use parsed config\n const dbUrl = `postgres://${config.username}:${config.password}@${config.host}:${config.port}`;\n \n return Response.json({ connected: true });\n } catch (error) {\n if (error instanceof SyntaxError) {\n return new Response(\"Invalid config JSON\", { status: 500 });\n }\n throw error;\n }\n }\n}\n```\n\nStore JSON secret:\n\n```bash\necho '{\"host\":\"db.example.com\",\"port\":5432,\"username\":\"app\",\"password\":\"secret\"}' | \\\n wrangler secrets-store secret create \\\n --name DB_CONFIG --scopes workers --remote\n```\n\n## Integration\n\n### Service Bindings\n\nAuth Worker signs JWT with Secrets Store; API Worker verifies via service binding.\n\nSee: [workers](../workers/) for service binding patterns.\n\nSee: [api.md](./api.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/smart-placement/README.md", "content": "# Cloudflare Workers Smart Placement\n\nAutomatic workload placement optimization to minimize latency by running Workers closer to backend infrastructure rather than end users.\n\n## Core Concept\n\nSmart Placement automatically analyzes Worker request duration across Cloudflare's global network and intelligently routes requests to optimal data center locations. Instead of defaulting to the location closest to the end user, Smart Placement can forward requests to locations closer to backend infrastructure when this reduces overall request duration.\n\n### When to Use\n\n**Enable Smart Placement when:**\n- Worker makes multiple round trips to backend services/databases\n- Backend infrastructure is geographically concentrated\n- Request duration dominated by backend latency rather than network latency from user\n- Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)\n- Worker uses `fetch` handler (not RPC methods)\n\n**Do NOT enable for:**\n- Workers serving only static content or cached responses\n- Workers without significant backend communication\n- Pure edge logic (auth checks, redirects, simple transformations)\n- Workers without fetch event handlers\n- Workers with RPC methods or named entrypoints (only `fetch` handlers are affected)\n- Pages/Assets Workers with `run_worker_first = true` (degrades asset serving)\n\n### Decision Tree\n\n```\nDoes your Worker have a fetch handler?\n├─ No → Smart Placement won't work (skip)\n└─ Yes\n │\n Does it make multiple backend calls (DB/API)?\n ├─ No → Don't enable (won't help)\n └─ Yes\n │\n Is backend geographically concentrated?\n ├─ No (globally distributed) → Probably won't help\n └─ Yes or uncertain\n │\n Does it serve static assets with run_worker_first=true?\n ├─ Yes → Don't enable (will hurt performance)\n └─ No → Enable Smart Placement\n │\n After 15min, check placement_status\n ├─ SUCCESS → Monitor metrics\n ├─ INSUFFICIENT_INVOCATIONS → Need more traffic\n └─ UNSUPPORTED_APPLICATION → Disable (hurting performance)\n```\n\n### Key Architecture Pattern\n\n**Recommended:** Split full-stack applications into separate Workers:\n```\nUser → Frontend Worker (at edge, close to user)\n ↓ Service Binding\n Backend Worker (Smart Placement enabled, close to DB/API)\n ↓\n Database/Backend Service\n```\n\nThis maintains fast, reactive frontends while optimizing backend latency.\n\n## Quick Start\n\n```jsonc\n// wrangler.jsonc\n{\n \"placement\": {\n \"mode\": \"smart\" // or \"off\" to explicitly disable\n }\n}\n```\n\nDeploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.\n\n**To disable:** Set `\"mode\": \"off\"` or remove `placement` field entirely (both equivalent).\n\n## Requirements\n\n- Wrangler 2.20.0+\n- Analysis time: Up to 15 minutes after enabling\n- Traffic requirements: Consistent traffic from multiple global locations\n- Available on all Workers plans (Free, Paid, Enterprise)\n\n## Placement Status Values\n\n```typescript\ntype PlacementStatus = \n | undefined // Not yet analyzed\n | 'SUCCESS' // Successfully optimized\n | 'INSUFFICIENT_INVOCATIONS' // Not enough traffic\n | 'UNSUPPORTED_APPLICATION'; // Made Worker slower (reverted)\n```\n\n## CLI Commands\n\n```bash\n# Deploy with Smart Placement\nwrangler deploy\n\n# Check placement status\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \\\n | jq .result.placement_status\n\n# Monitor\nwrangler tail your-worker-name --header cf-placement\n```\n\n## Reading Order\n\n**First time?** Start here:\n1. This README - understand core concepts and when to use Smart Placement\n2. [configuration.md](./configuration.md) - set up wrangler.jsonc and understand limitations\n3. [patterns.md](./patterns.md) - see practical examples for your use case\n4. [api.md](./api.md) - monitor and verify Smart Placement is working\n5. [gotchas.md](./gotchas.md) - troubleshoot common issues\n\n**Quick lookup:**\n- \"Should I enable Smart Placement?\" → See \"When to Use\" above\n- \"How do I configure it?\" → [configuration.md](./configuration.md)\n- \"How do I split frontend/backend?\" → [patterns.md](./patterns.md)\n- \"Why isn't it working?\" → [gotchas.md](./gotchas.md)\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, mode values, validation rules\n- [api.md](./api.md) - Placement Status API, cf-placement header, monitoring\n- [patterns.md](./patterns.md) - Frontend/backend split, database workers, SSR patterns\n- [gotchas.md](./gotchas.md) - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues\n\n## See Also\n\n- [workers](../workers/) - Worker runtime and fetch handlers\n- [d1](../d1/) - D1 database that benefits from Smart Placement\n- [durable-objects](../durable-objects/) - Durable Objects with backend logic\n- [bindings](../bindings/) - Service bindings for frontend/backend split\n" }, { "path": "skills/.curated/cloudflare-deploy/references/smart-placement/api.md", "content": "# Smart Placement API\n\n## Placement Status API\n\nQuery Worker placement status via Cloudflare API:\n\n```bash\ncurl -X GET \"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME}\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\"\n```\n\nResponse includes `placement_status` field:\n\n```typescript\ntype PlacementStatus = \n | undefined // Not yet analyzed\n | 'SUCCESS' // Successfully optimized\n | 'INSUFFICIENT_INVOCATIONS' // Not enough traffic\n | 'UNSUPPORTED_APPLICATION'; // Made Worker slower (reverted)\n```\n\n## Status Meanings\n\n**`undefined` (not present)**\n- Worker not yet analyzed\n- Always runs at default edge location closest to user\n\n**`SUCCESS`**\n- Analysis complete, Smart Placement active\n- Worker runs in optimal location (may be edge or remote)\n\n**`INSUFFICIENT_INVOCATIONS`**\n- Not enough requests to make placement decision\n- Requires consistent multi-region traffic\n- Always runs at default edge location\n\n**`UNSUPPORTED_APPLICATION`** (rare, <1% of Workers)\n- Smart Placement made Worker slower\n- Placement decision reverted\n- Always runs at edge location\n- Won't be re-analyzed until redeployed\n\n## cf-placement Header (Beta)\n\nSmart Placement adds response header indicating routing decision:\n\n```typescript\n// Remote placement (Smart Placement routed request)\n\"cf-placement: remote-LHR\" // Routed to London\n\n// Local placement (default edge routing) \n\"cf-placement: local-EWR\" // Stayed at Newark edge\n```\n\nFormat: `{placement-type}-{IATA-code}`\n- `remote-*` = Smart Placement routed to remote location\n- `local-*` = Stayed at default edge location\n- IATA code = nearest airport to data center\n\n**Warning:** Beta feature, may be removed before GA.\n\n## Detecting Smart Placement in Code\n\n**Note:** `cf-placement` header is a beta feature and may change or be removed.\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const placementHeader = request.headers.get('cf-placement');\n \n if (placementHeader?.startsWith('remote-')) {\n const location = placementHeader.split('-')[1];\n console.log(`Smart Placement routed to ${location}`);\n } else if (placementHeader?.startsWith('local-')) {\n const location = placementHeader.split('-')[1];\n console.log(`Running at edge location ${location}`);\n }\n \n return new Response('OK');\n }\n} satisfies ExportedHandler;\n```\n\n## Request Duration Metrics\n\nAvailable in Cloudflare dashboard when Smart Placement enabled:\n\n**Workers & Pages → [Your Worker] → Metrics → Request Duration**\n\nShows histogram comparing:\n- Request duration WITH Smart Placement (99% of traffic)\n- Request duration WITHOUT Smart Placement (1% baseline)\n\n**Request Duration vs Execution Duration:**\n- **Request duration:** Total time from request arrival to response delivery (includes network latency)\n- **Execution duration:** Time Worker code actively executing (excludes network waits)\n\nUse request duration to measure Smart Placement impact.\n\n### Interpreting Metrics\n\n| Metric Comparison | Interpretation | Action |\n|-------------------|----------------|--------|\n| WITH < WITHOUT | Smart Placement helping | Keep enabled |\n| WITH ≈ WITHOUT | Neutral impact | Consider disabling to free resources |\n| WITH > WITHOUT | Smart Placement hurting | Disable with `mode: \"off\"` |\n\n**Why Smart Placement might hurt performance:**\n- Worker primarily serves static assets or cached content\n- Backend services are globally distributed (no single optimal location)\n- Worker has minimal backend communication\n- Using Pages with `assets.run_worker_first = true`\n\n**Typical improvements when Smart Placement helps:**\n- 20-50% reduction in request duration for database-heavy Workers\n- 30-60% reduction for Workers making multiple backend API calls\n- Larger improvements when backend is geographically concentrated\n\n## Monitoring Commands\n\n```bash\n# Tail Worker logs\nwrangler tail your-worker-name\n\n# Tail with filters\nwrangler tail your-worker-name --status error\nwrangler tail your-worker-name --header cf-placement\n\n# Check placement status via API\ncurl -H \"Authorization: Bearer $TOKEN\" \\\n https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \\\n | jq .result.placement_status\n```\n\n## TypeScript Types\n\n```typescript\n// Placement status returned by API (field may be absent)\ntype PlacementStatus = \n | 'SUCCESS'\n | 'INSUFFICIENT_INVOCATIONS'\n | 'UNSUPPORTED_APPLICATION'\n | undefined;\n\n// Placement configuration in wrangler.jsonc\ntype PlacementMode = 'smart' | 'off';\n\ninterface PlacementConfig {\n mode: PlacementMode;\n // Legacy fields (deprecated/removed):\n // hint?: string; // REMOVED - no longer supported\n}\n\n// Explicit placement (separate feature from Smart Placement)\ninterface ExplicitPlacementConfig {\n region?: string;\n host?: string;\n hostname?: string;\n // Cannot combine with mode field\n}\n\n// Worker metadata from API response\ninterface WorkerMetadata {\n placement?: PlacementConfig | ExplicitPlacementConfig;\n placement_status?: PlacementStatus;\n}\n\n// Service Binding for backend Worker\ninterface Env {\n BACKEND_SERVICE: Fetcher; // Service Binding to backend Worker\n DATABASE: D1Database;\n}\n\n// Example Worker with Service Binding\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // Forward to backend Worker with Smart Placement enabled\n const response = await env.BACKEND_SERVICE.fetch(request);\n return response;\n }\n} satisfies ExportedHandler;\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/smart-placement/configuration.md", "content": "# Smart Placement Configuration\n\n## wrangler.jsonc Setup\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"placement\": {\n \"mode\": \"smart\"\n }\n}\n```\n\n## Placement Mode Values\n\n| Mode | Behavior |\n|------|----------|\n| `\"smart\"` | Enable Smart Placement - automatic optimization based on traffic analysis |\n| `\"off\"` | Explicitly disable Smart Placement - always run at edge closest to user |\n| Not specified | Default behavior - run at edge closest to user (same as `\"off\"`) |\n\n**Note:** Smart Placement vs Explicit Placement are separate features. Smart Placement (`mode: \"smart\"`) uses automatic analysis. For manual placement control, see explicit placement options (`region`, `host`, `hostname` fields - not covered in this reference).\n\n## Frontend + Backend Split Configuration\n\n### Frontend Worker (No Smart Placement)\n\n```jsonc\n// frontend-worker/wrangler.jsonc\n{\n \"name\": \"frontend\",\n \"main\": \"frontend-worker.ts\",\n // No \"placement\" - runs at edge\n \"services\": [\n {\n \"binding\": \"BACKEND\",\n \"service\": \"backend-api\"\n }\n ]\n}\n```\n\n### Backend Worker (Smart Placement Enabled)\n\n```jsonc\n// backend-api/wrangler.jsonc\n{\n \"name\": \"backend-api\",\n \"main\": \"backend-worker.ts\",\n \"placement\": {\n \"mode\": \"smart\"\n },\n \"d1_databases\": [\n {\n \"binding\": \"DATABASE\",\n \"database_id\": \"xxx\"\n }\n ]\n}\n```\n\n## Requirements & Limitations\n\n### Requirements\n- **Wrangler version:** 2.20.0+\n- **Analysis time:** Up to 15 minutes\n- **Traffic requirements:** Consistent multi-location traffic\n- **Workers plan:** All plans (Free, Paid, Enterprise)\n\n### What Smart Placement Affects\n\n**CRITICAL LIMITATION - Smart Placement ONLY Affects `fetch` Handlers:**\n\nSmart Placement is fundamentally limited to Workers with default `fetch` handlers. This is a key architectural constraint.\n\n- ✅ **Affects:** `fetch` event handlers ONLY (the default export's fetch method)\n- ❌ **Does NOT affect:** \n - RPC methods (Service Bindings with `WorkerEntrypoint` - see example below)\n - Named entrypoints (exports other than `default`)\n - Workers without `fetch` handlers\n - Queue consumers, scheduled handlers, or other event types\n\n**Example - Smart Placement ONLY affects `fetch`:**\n```typescript\n// ✅ Smart Placement affects this:\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // This runs close to backend when Smart Placement enabled\n const data = await env.DATABASE.prepare('SELECT * FROM users').all();\n return Response.json(data);\n }\n}\n\n// ❌ Smart Placement DOES NOT affect these:\nexport class MyRPC extends WorkerEntrypoint {\n async myMethod() { \n // This ALWAYS runs at edge, Smart Placement has NO EFFECT\n const data = await this.env.DATABASE.prepare('SELECT * FROM users').all();\n return data;\n }\n}\n\nexport async function scheduled(event: ScheduledEvent, env: Env) {\n // NOT affected by Smart Placement\n}\n```\n\n**Consequence:** If your backend logic uses RPC methods (`WorkerEntrypoint`), Smart Placement cannot optimize those calls. You must use fetch-based patterns for Smart Placement to work.\n\n**Solution:** Convert RPC methods to fetch endpoints, or use a wrapper Worker with `fetch` handler that calls your backend RPC (though this adds latency).\n\n### Baseline Traffic\nSmart Placement automatically routes 1% of requests WITHOUT optimization as baseline for performance comparison.\n\n### Validation Rules\n\n**Mutually exclusive fields:**\n- `mode` cannot be used with explicit placement fields (`region`, `host`, `hostname`)\n- Choose either Smart Placement OR explicit placement, not both\n\n```jsonc\n// ✅ Valid - Smart Placement\n{ \"placement\": { \"mode\": \"smart\" } }\n\n// ✅ Valid - Explicit Placement (different feature)\n{ \"placement\": { \"region\": \"us-east1\" } }\n\n// ❌ Invalid - Cannot combine\n{ \"placement\": { \"mode\": \"smart\", \"region\": \"us-east1\" } }\n```\n\n## Dashboard Configuration\n\n**Workers & Pages** → Select Worker → **Settings** → **General** → **Placement: Smart** → Wait 15min → Check **Metrics**\n\n## TypeScript Types\n\n```typescript\ninterface Env {\n BACKEND: Fetcher;\n DATABASE: D1Database;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const data = await env.DATABASE.prepare('SELECT * FROM table').all();\n return Response.json(data);\n }\n} satisfies ExportedHandler;\n```\n\n## Cloudflare Pages/Assets Warning\n\n**CRITICAL PERFORMANCE ISSUE:** Enabling Smart Placement with `assets.run_worker_first = true` in Pages projects **severely degrades asset serving performance**. This is one of the most common misconfigurations.\n\n**Why this is bad:**\n- Smart Placement routes ALL requests (including static assets) away from edge to remote locations\n- Static assets (HTML, CSS, JS, images) should ALWAYS be served from edge closest to user\n- Result: 2-5x slower asset loading times, poor user experience\n\n**Problem:** Smart Placement routes asset requests away from edge, but static assets should always be served from edge closest to user.\n\n**Solutions (in order of preference):**\n1. **Recommended:** Split into separate Workers (frontend at edge + backend with Smart Placement)\n2. Set `\"mode\": \"off\"` to explicitly disable Smart Placement for Pages/Assets Workers\n3. Use `assets.run_worker_first = false` (serves assets first, bypasses Worker for static content)\n\n```jsonc\n// ❌ BAD - Degrades asset performance by 2-5x\n{\n \"name\": \"pages-app\",\n \"placement\": { \"mode\": \"smart\" },\n \"assets\": { \"run_worker_first\": true }\n}\n\n// ✅ GOOD - Frontend at edge, backend optimized\n// frontend-worker/wrangler.jsonc\n{\n \"name\": \"frontend\",\n \"assets\": { \"run_worker_first\": true }\n // No placement - runs at edge\n}\n\n// backend-worker/wrangler.jsonc\n{\n \"name\": \"backend-api\",\n \"placement\": { \"mode\": \"smart\" },\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_id\": \"xxx\" }]\n}\n```\n\n**Key takeaway:** Never enable Smart Placement on Workers that serve static assets with `run_worker_first = true`.\n\n## Local Development\n\nSmart Placement does NOT work in `wrangler dev` (local only). Test by deploying: `wrangler deploy --env staging`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/smart-placement/gotchas.md", "content": "# Smart Placement Gotchas\n\n## Common Errors\n\n### \"INSUFFICIENT_INVOCATIONS\"\n\n**Cause:** Not enough traffic for Smart Placement to analyze\n**Solution:**\n- Ensure Worker receives consistent global traffic\n- Wait longer (analysis takes up to 15 minutes)\n- Send test traffic from multiple global locations\n- Check Worker has fetch event handler\n\n### \"UNSUPPORTED_APPLICATION\"\n\n**Cause:** Smart Placement made Worker slower rather than faster\n**Reasons:**\n- Worker doesn't make backend calls (runs faster at edge)\n- Backend calls are cached (network latency to user more important)\n- Backend service has good global distribution\n- Worker serves static assets or Pages content\n\n**Solutions:**\n- Disable Smart Placement: `{ \"placement\": { \"mode\": \"off\" } }`\n- Review whether Worker actually benefits from Smart Placement\n- Consider caching strategy to reduce backend calls\n- For Pages/Assets Workers, use separate backend Worker with Smart Placement\n\n### \"No request duration metrics\"\n\n**Cause:** Smart Placement not enabled, insufficient time passed, insufficient traffic, or analysis incomplete\n**Solution:**\n- Ensure Smart Placement enabled in config\n- Wait 15+ minutes after deployment\n- Verify Worker has sufficient traffic\n- Check `placement_status` is `SUCCESS`\n\n### \"cf-placement header missing\"\n\n**Cause:** Smart Placement not enabled, beta feature removed, or Worker not analyzed yet\n**Solution:** Verify Smart Placement enabled, wait for analysis (15min), check if beta feature still available\n\n## Pages/Assets + Smart Placement Performance Degradation\n\n**Problem:** Static assets load 2-5x slower when Smart Placement enabled with `run_worker_first = true`.\n\n**Cause:** Smart Placement routes ALL requests (including static assets like HTML, CSS, JS, images) to remote locations. Static content should ALWAYS be served from edge closest to user.\n\n**Solution:** Split into separate Workers OR disable Smart Placement:\n```jsonc\n// ❌ BAD - Assets routed away from user\n{\n \"name\": \"pages-app\",\n \"placement\": { \"mode\": \"smart\" },\n \"assets\": { \"run_worker_first\": true }\n}\n\n// ✅ GOOD - Assets at edge, API optimized\n// frontend/wrangler.jsonc\n{\n \"name\": \"frontend\",\n \"assets\": { \"run_worker_first\": true }\n // No placement field - stays at edge\n}\n\n// backend/wrangler.jsonc\n{\n \"name\": \"backend-api\",\n \"placement\": { \"mode\": \"smart\" }\n}\n```\n\nThis is one of the most common and impactful Smart Placement misconfigurations.\n\n## Monolithic Full-Stack Worker\n\n**Problem:** Frontend and backend logic in single Worker with Smart Placement enabled.\n\n**Cause:** Smart Placement optimizes for backend latency but increases user-facing response time.\n\n**Solution:** Split into two Workers:\n```jsonc\n// frontend/wrangler.jsonc\n{\n \"name\": \"frontend\",\n \"placement\": { \"mode\": \"off\" }, // Explicit: stay at edge\n \"services\": [{ \"binding\": \"BACKEND\", \"service\": \"backend-api\" }]\n}\n\n// backend/wrangler.jsonc\n{\n \"name\": \"backend-api\",\n \"placement\": { \"mode\": \"smart\" },\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_id\": \"xxx\" }]\n}\n```\n\n## Local Development Confusion\n\n**Issue:** Smart Placement doesn't work in `wrangler dev`.\n\n**Explanation:** Smart Placement only activates in production deployments, not local development.\n\n**Solution:** Test Smart Placement in staging environment: `wrangler deploy --env staging`\n\n## Baseline Traffic & Analysis Time\n\n**Note:** Smart Placement routes 1% of requests WITHOUT optimization for comparison (expected).\n\n**Analysis time:** Up to 15 minutes. During analysis, Worker runs at edge. Monitor `placement_status`.\n\n## RPC Methods Not Affected (Critical Limitation)\n\n**Problem:** Enabled Smart Placement on backend but RPC calls still slow.\n\n**Cause:** Smart Placement ONLY affects `fetch` handlers. RPC methods (Service Bindings with `WorkerEntrypoint`) are NEVER affected.\n\n**Why:** RPC bypasses `fetch` handler - Smart Placement can only route `fetch` requests.\n\n**Solution:** Convert to fetch-based Service Bindings:\n\n```typescript\n// ❌ RPC - Smart Placement has NO EFFECT\nexport class BackendRPC extends WorkerEntrypoint {\n async getData() {\n // ALWAYS runs at edge\n return await this.env.DATABASE.prepare('SELECT * FROM table').all();\n }\n}\n\n// ✅ Fetch - Smart Placement WORKS\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // Runs close to DATABASE when Smart Placement enabled\n const data = await env.DATABASE.prepare('SELECT * FROM table').all();\n return Response.json(data);\n }\n}\n```\n\n## Requirements\n\n- **Wrangler 2.20.0+** required\n- **Consistent multi-region traffic** needed for analysis\n- **Only affects fetch handlers** - RPC methods and named entrypoints not affected\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Analysis time | Up to 15 minutes | After enabling |\n| Baseline traffic | 1% | Routed without optimization |\n| Min Wrangler version | 2.20.0+ | Required |\n| Traffic requirement | Multi-region | Consistent needed |\n\n## Disabling Smart Placement\n\n```jsonc\n{ \"placement\": { \"mode\": \"off\" } } // Explicit disable\n// OR remove \"placement\" field entirely (same effect)\n```\n\nBoth behaviors identical - Worker runs at edge closest to user.\n\n## When NOT to Use Smart Placement\n\n- Workers serving only static content or cached responses\n- Workers without significant backend communication\n- Pure edge logic (auth checks, redirects, simple transformations)\n- Workers without fetch event handlers\n- Pages/Assets Workers with `run_worker_first = true`\n- Workers using RPC methods instead of fetch handlers\n\nThese scenarios won't benefit and may perform worse with Smart Placement.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/smart-placement/patterns.md", "content": "# Smart Placement Patterns\n\n## Backend Worker with Database Access\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const user = await env.DATABASE.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();\n const orders = await env.DATABASE.prepare('SELECT * FROM orders WHERE user_id = ?').bind(userId).all();\n return Response.json({ user, orders });\n }\n};\n```\n\n```jsonc\n{ \"placement\": { \"mode\": \"smart\" }, \"d1_databases\": [{ \"binding\": \"DATABASE\", \"database_id\": \"xxx\" }] }\n```\n\n## Frontend + Backend Split (Service Bindings)\n\n**Frontend:** Runs at edge for fast user response\n**Backend:** Smart Placement runs close to database\n\n```typescript\n// Frontend Worker - routes requests to backend\ninterface Env {\n BACKEND: Fetcher; // Service Binding to backend Worker\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n if (new URL(request.url).pathname.startsWith('/api/')) {\n return env.BACKEND.fetch(request); // Forward to backend\n }\n return new Response('Frontend content');\n }\n};\n\n// Backend Worker - database operations\ninterface BackendEnv {\n DATABASE: D1Database;\n}\n\nexport default {\n async fetch(request: Request, env: BackendEnv): Promise {\n const data = await env.DATABASE.prepare('SELECT * FROM table').all();\n return Response.json(data);\n }\n};\n```\n\n**CRITICAL:** Use fetch-based Service Bindings (shown above). If using RPC with `WorkerEntrypoint`, Smart Placement will NOT optimize those method calls - only `fetch` handlers are affected.\n\n**RPC vs Fetch - CRITICAL:** Smart Placement ONLY works with fetch-based bindings, NOT RPC.\n\n```typescript\n// ❌ RPC - Smart Placement has NO EFFECT on backend RPC methods\nexport class BackendRPC extends WorkerEntrypoint {\n async getData() {\n // ALWAYS runs at edge, Smart Placement ignored\n return await this.env.DATABASE.prepare('SELECT * FROM table').all();\n }\n}\n\n// ✅ Fetch - Smart Placement WORKS\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // Runs close to DATABASE when Smart Placement enabled\n const data = await env.DATABASE.prepare('SELECT * FROM table').all();\n return Response.json(data);\n }\n};\n```\n\n## External API Integration\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const apiUrl = 'https://api.partner.com';\n const headers = { 'Authorization': `Bearer ${env.API_KEY}` };\n \n const [profile, transactions] = await Promise.all([\n fetch(`${apiUrl}/profile`, { headers }),\n fetch(`${apiUrl}/transactions`, { headers })\n ]);\n \n return Response.json({ \n profile: await profile.json(), \n transactions: await transactions.json()\n });\n }\n};\n```\n\n## SSR / API Gateway Pattern\n\n```typescript\n// Frontend (edge) - auth/routing close to user\nexport default {\n async fetch(request: Request, env: Env) {\n if (!request.headers.get('Authorization')) {\n return new Response('Unauthorized', { status: 401 });\n }\n const data = await env.BACKEND.fetch(request);\n return new Response(renderPage(await data.json()), { \n headers: { 'Content-Type': 'text/html' } \n });\n }\n};\n\n// Backend (Smart Placement) - DB operations close to data\nexport default {\n async fetch(request: Request, env: Env) {\n const data = await env.DATABASE.prepare('SELECT * FROM pages WHERE id = ?').bind(pageId).first();\n return Response.json(data);\n }\n};\n```\n\n## Durable Objects with Smart Placement\n\n**Key principle:** Smart Placement does NOT control WHERE Durable Objects run. DOs always run in their designated region (based on jurisdiction or smart location hints).\n\n**What Smart Placement DOES affect:** The location of the coordinator Worker's `fetch` handler that makes calls to multiple DOs.\n\n**Pattern:** Enable Smart Placement on coordinator Worker that aggregates data from multiple DOs:\n\n```typescript\n// Worker with Smart Placement - aggregates data from multiple DOs\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const userId = new URL(request.url).searchParams.get('user');\n \n // Get DO stubs\n const userDO = env.USER_DO.get(env.USER_DO.idFromName(userId));\n const analyticsID = env.ANALYTICS_DO.idFromName(`analytics-${userId}`);\n const analyticsDO = env.ANALYTICS_DO.get(analyticsID);\n \n // Fetch from multiple DOs\n const [userData, analyticsData] = await Promise.all([\n userDO.fetch(new Request('https://do/profile')),\n analyticsDO.fetch(new Request('https://do/stats'))\n ]);\n \n return Response.json({\n user: await userData.json(),\n analytics: await analyticsData.json()\n });\n }\n};\n```\n\n```jsonc\n// wrangler.jsonc\n{\n \"placement\": { \"mode\": \"smart\" },\n \"durable_objects\": {\n \"bindings\": [\n { \"name\": \"USER_DO\", \"class_name\": \"UserDO\" },\n { \"name\": \"ANALYTICS_DO\", \"class_name\": \"AnalyticsDO\" }\n ]\n }\n}\n```\n\n**When this helps:** \n- Worker's `fetch` handler runs closer to DO regions, reducing network latency for multiple DO calls\n- Most beneficial when DOs are geographically concentrated or in specific jurisdictions\n- Helps when coordinator makes many sequential or parallel DO calls\n\n**When this DOESN'T help:**\n- DOs are globally distributed (no single optimal Worker location)\n- Worker only calls a single DO\n- DO calls are infrequent or cached\n\n## Best Practices\n\n- Split full-stack apps: frontend at edge, backend with Smart Placement\n- Use fetch-based Service Bindings (not RPC)\n- Enable for backend logic: APIs, data aggregation, DB operations\n- Don't enable for: static content, edge logic, RPC methods, Pages with `run_worker_first`\n- Wait 15+ min for analysis, verify `placement_status = SUCCESS`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/snippets/README.md", "content": "# Cloudflare Snippets Skill Reference\n\n## Description\nExpert guidance for **Cloudflare Snippets ONLY** - a lightweight JavaScript-based edge logic platform for modifying HTTP requests and responses. Snippets run as part of the Ruleset Engine and are included at no additional cost on paid plans (Pro, Business, Enterprise).\n\n## What Are Snippets?\nSnippets are JavaScript functions executed at the edge as part of Cloudflare's Ruleset Engine. Key characteristics:\n- **Execution time**: 5ms CPU limit per request\n- **Size limit**: 32KB per snippet\n- **Runtime**: V8 isolate (subset of Workers APIs)\n- **Subrequests**: 2-5 fetch calls depending on plan\n- **Cost**: Included with Pro/Business/Enterprise plans\n\n## Snippets vs Workers Decision Matrix\n\n| Factor | Choose Snippets If... | Choose Workers If... |\n|--------|----------------------|---------------------|\n| **Complexity** | Simple request/response modifications | Complex business logic, routing, middleware |\n| **Execution time** | <5ms sufficient | Need >5ms or variable time |\n| **Subrequests** | 2-5 fetch calls sufficient | Need >5 subrequests or complex orchestration |\n| **Code size** | <32KB sufficient | Need >32KB or npm dependencies |\n| **Cost** | Want zero additional cost | Can afford $5/mo + usage |\n| **APIs** | Need basic fetch, headers, URL | Need KV, D1, R2, Durable Objects, cron triggers |\n| **Deployment** | Need rule-based triggers | Want custom routing logic |\n\n**Rule of thumb**: Use Snippets for modifications, Workers for applications.\n\n## Execution Model\n1. Request arrives at Cloudflare edge\n2. Ruleset Engine evaluates snippet rules (filter expressions)\n3. If rule matches, snippet executes within 5ms limit\n4. Modified request/response continues through pipeline\n5. Response returned to client\n\nSnippets execute synchronously in the request path - performance is critical.\n\n## Reading Order\n1. **[configuration.md](configuration.md)** - Start here: setup, deployment methods (Dashboard/API/Terraform)\n2. **[api.md](api.md)** - Core APIs: Request, Response, headers, `request.cf` properties\n3. **[patterns.md](patterns.md)** - Real-world examples: geo-routing, A/B tests, security headers\n4. **[gotchas.md](gotchas.md)** - Troubleshooting: common errors, performance tips, API limitations\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, configuration\n- **[api.md](api.md)** - API endpoints, methods, interfaces\n- **[patterns.md](patterns.md)** - Common patterns, use cases, examples\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations\n\n## Quick Start\n```javascript\n// Snippet: Add security headers\nexport default {\n async fetch(request) {\n const response = await fetch(request);\n const newResponse = new Response(response.body, response);\n newResponse.headers.set(\"X-Frame-Options\", \"DENY\");\n newResponse.headers.set(\"X-Content-Type-Options\", \"nosniff\");\n return newResponse;\n }\n}\n```\n\nDeploy via Dashboard (Rules → Snippets) or API/Terraform. See configuration.md for details.\n\n## See Also\n\n- [Cloudflare Docs](https://developers.cloudflare.com/rules/snippets/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/snippets/api.md", "content": "# Snippets API Reference\n\n## Request Object\n\n### HTTP Properties\n```javascript\nrequest.method // GET, POST, PUT, DELETE, etc.\nrequest.url // Full URL string\nrequest.headers // Headers object\nrequest.body // ReadableStream (for POST/PUT)\nrequest.cf // Cloudflare properties (see below)\n```\n\n### URL Operations\n```javascript\nconst url = new URL(request.url);\nurl.hostname // \"example.com\"\nurl.pathname // \"/path/to/page\"\nurl.search // \"?query=value\"\nurl.searchParams.get(\"q\") // \"value\"\nurl.searchParams.set(\"q\", \"new\")\nurl.searchParams.delete(\"q\")\n```\n\n### Header Operations\n```javascript\n// Read headers\nrequest.headers.get(\"User-Agent\")\nrequest.headers.has(\"Authorization\")\nrequest.headers.getSetCookie() // Get all Set-Cookie headers\n\n// Modify headers (create new request)\nconst modifiedRequest = new Request(request);\nmodifiedRequest.headers.set(\"X-Custom\", \"value\")\nmodifiedRequest.headers.delete(\"X-Remove\")\n```\n\n### Cloudflare Properties (`request.cf`)\nAccess Cloudflare-specific metadata about the request:\n\n```javascript\n// Geolocation\nrequest.cf.city // \"San Francisco\"\nrequest.cf.continent // \"NA\"\nrequest.cf.country // \"US\"\nrequest.cf.region // \"California\" or \"CA\"\nrequest.cf.regionCode // \"CA\"\nrequest.cf.postalCode // \"94102\"\nrequest.cf.latitude // \"37.7749\"\nrequest.cf.longitude // \"-122.4194\"\nrequest.cf.timezone // \"America/Los_Angeles\"\nrequest.cf.metroCode // \"807\" (DMA code)\n\n// Network\nrequest.cf.colo // \"SFO\" (airport code of datacenter)\nrequest.cf.asn // 13335 (ASN number)\nrequest.cf.asOrganization // \"Cloudflare, Inc.\"\n\n// Bot Management (if enabled)\nrequest.cf.botManagement.score // 1-99 (1=bot, 99=human)\nrequest.cf.botManagement.verified_bot // true/false\nrequest.cf.botManagement.static_resource // true/false\n\n// TLS/HTTP version\nrequest.cf.tlsVersion // \"TLSv1.3\"\nrequest.cf.tlsCipher // \"AEAD-AES128-GCM-SHA256\"\nrequest.cf.httpProtocol // \"HTTP/2\"\n\n// Request metadata\nrequest.cf.requestPriority // \"weight=192;exclusive=0\"\n```\n\n**Use cases**: Geo-routing, bot detection, security decisions, analytics.\n\n## Response Object\n\n### Response Constructors\n```javascript\n// Plain text\nnew Response(\"Hello\", { status: 200 })\n\n// JSON\nResponse.json({ key: \"value\" }, { status: 200 })\n\n// HTML\nnew Response(\"

Hi

\", { \n status: 200,\n headers: { \"Content-Type\": \"text/html\" }\n})\n\n// Redirect\nResponse.redirect(\"https://example.com\", 301) // or 302\n\n// Stream (pass through)\nnew Response(response.body, response)\n```\n\n### Response Headers\n```javascript\n// Create modified response\nconst newResponse = new Response(response.body, response);\n\n// Set/modify headers\nnewResponse.headers.set(\"X-Custom\", \"value\")\nnewResponse.headers.append(\"Set-Cookie\", \"session=abc; Path=/\")\nnewResponse.headers.delete(\"Server\")\n\n// Common headers\nnewResponse.headers.set(\"Cache-Control\", \"public, max-age=3600\")\nnewResponse.headers.set(\"Content-Type\", \"application/json\")\n```\n\n### Response Properties\n```javascript\nresponse.status // 200, 404, 500, etc.\nresponse.statusText // \"OK\", \"Not Found\", etc.\nresponse.headers // Headers object\nresponse.body // ReadableStream\nresponse.ok // true if status 200-299\nresponse.redirected // true if redirected\n```\n\n## REST API Operations\n\n### List Snippets\n```bash\nGET /zones/{zone_id}/snippets\n```\n\n### Get Snippet\n```bash\nGET /zones/{zone_id}/snippets/{snippet_name}\n```\n\n### Create/Update Snippet\n```bash\nPUT /zones/{zone_id}/snippets/{snippet_name}\nContent-Type: multipart/form-data\n\nfiles=@snippet.js\nmetadata={\"main_module\":\"snippet.js\"}\n```\n\n### Delete Snippet\n```bash\nDELETE /zones/{zone_id}/snippets/{snippet_name}\n```\n\n### List Snippet Rules\n```bash\nGET /zones/{zone_id}/rulesets/phases/http_request_snippets/entrypoint\n```\n\n### Update Snippet Rules\n```bash\nPUT /zones/{zone_id}/snippets/snippet_rules\nContent-Type: application/json\n\n{\n \"rules\": [{\n \"description\": \"Apply snippet\",\n \"enabled\": true,\n \"expression\": \"http.host eq \\\"example.com\\\"\",\n \"snippet_name\": \"my_snippet\"\n }]\n}\n```\n\n## Available APIs in Snippets\n\n### ✅ Supported\n- `fetch()` - HTTP requests (2-5 subrequests per plan)\n- `Request` / `Response` - Standard Web APIs\n- `URL` / `URLSearchParams` - URL manipulation\n- `Headers` - Header manipulation\n- `TextEncoder` / `TextDecoder` - Text encoding\n- `crypto.subtle` - Web Crypto API (hashing, signing)\n- `crypto.randomUUID()` - UUID generation\n\n### ❌ Not Supported in Snippets\n- `caches` API - Not available (use Workers)\n- `KV`, `D1`, `R2` - Storage APIs (use Workers)\n- `Durable Objects` - Stateful objects (use Workers)\n- `WebSocket` - WebSocket upgrades (use Workers)\n- `HTMLRewriter` - HTML parsing (use Workers)\n- `import` statements - No module imports\n- `addEventListener` - Use `export default { async fetch() {}` pattern\n\n## Snippet Structure\n```javascript\nexport default {\n async fetch(request) {\n // Your logic here\n const response = await fetch(request);\n return response; // or modified response\n }\n}\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/snippets/configuration.md", "content": "# Snippets Configuration Guide\n\n## Configuration Methods\n\n### 1. Dashboard (GUI)\n**Best for**: Quick tests, single snippets, visual rule building\n\n```\n1. Go to zone → Rules → Snippets\n2. Click \"Create Snippet\" or select template\n3. Enter snippet name (a-z, 0-9, _ only, cannot change later)\n4. Write JavaScript code (32KB max)\n5. Configure snippet rule:\n - Expression Builder (visual) or Expression Editor (text)\n - Use Ruleset Engine filter expressions\n6. Test with Preview/HTTP tabs\n7. Deploy or Save as Draft\n```\n\n### 2. REST API\n**Best for**: CI/CD, automation, programmatic management\n\n```bash\n# Create/update snippet\ncurl \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME\" \\\n --request PUT \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\" \\\n --form \"files=@example.js\" \\\n --form \"metadata={\\\"main_module\\\": \\\"example.js\\\"}\"\n\n# Create snippet rule\ncurl \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/snippet_rules\" \\\n --request PUT \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"rules\": [\n {\n \"description\": \"Trigger snippet on /api paths\",\n \"enabled\": true,\n \"expression\": \"starts_with(http.request.uri.path, \\\"/api/\\\")\",\n \"snippet_name\": \"api_snippet\"\n }\n ]\n }'\n\n# List snippets\ncurl \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets\" \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\"\n\n# Delete snippet\ncurl \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/snippets/$SNIPPET_NAME\" \\\n --request DELETE \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\"\n```\n\n### 3. Terraform\n**Best for**: Infrastructure-as-code, multi-zone deployments\n\n```hcl\n# Configure Terraform provider\nterraform {\n required_providers {\n cloudflare = {\n source = \"cloudflare/cloudflare\"\n version = \"~> 4.0\"\n }\n }\n}\n\nprovider \"cloudflare\" {\n api_token = var.cloudflare_api_token\n}\n\n# Create snippet\nresource \"cloudflare_snippet\" \"security_headers\" {\n zone_id = var.zone_id\n name = \"security_headers\"\n \n main_module = \"security_headers.js\"\n files {\n name = \"security_headers.js\"\n content = file(\"${path.module}/snippets/security_headers.js\")\n }\n}\n\n# Create snippet rule\nresource \"cloudflare_snippet_rules\" \"security_rules\" {\n zone_id = var.zone_id\n \n rules {\n description = \"Apply security headers to all requests\"\n enabled = true\n expression = \"true\"\n snippet_name = cloudflare_snippet.security_headers.name\n }\n}\n```\n\n### 4. Pulumi\n**Best for**: Multi-cloud IaC, TypeScript/Python/Go workflows\n\n```typescript\nimport * as cloudflare from \"@pulumi/cloudflare\";\nimport * as fs from \"fs\";\n\n// Create snippet\nconst securitySnippet = new cloudflare.Snippet(\"security-headers\", {\n zoneId: zoneId,\n name: \"security_headers\",\n mainModule: \"security_headers.js\",\n files: [{\n name: \"security_headers.js\",\n content: fs.readFileSync(\"./snippets/security_headers.js\", \"utf8\"),\n }],\n});\n\n// Create snippet rule\nconst snippetRule = new cloudflare.SnippetRules(\"security-rules\", {\n zoneId: zoneId,\n rules: [{\n description: \"Apply security headers\",\n enabled: true,\n expression: \"true\",\n snippetName: securitySnippet.name,\n }],\n});\n```\n\n## Filter Expressions\n\nSnippets use Cloudflare's Ruleset Engine expression language to determine when to execute.\n\n### Common Expression Patterns\n\n```javascript\n// Host matching\nhttp.host eq \"example.com\"\nhttp.host in {\"example.com\" \"www.example.com\"}\nhttp.host contains \"example\"\n\n// Path matching\nhttp.request.uri.path eq \"/api/users\"\nstarts_with(http.request.uri.path, \"/api/\")\nends_with(http.request.uri.path, \".json\")\nmatches(http.request.uri.path, \"^/api/v[0-9]+/\")\n\n// Query parameters\nhttp.request.uri.query contains \"debug=true\"\n\n// Headers\nhttp.headers[\"user-agent\"] contains \"Mobile\"\nhttp.headers[\"accept-language\"] eq \"en-US\"\n\n// Cookies\nhttp.cookie contains \"session=\"\n\n// Geolocation\nip.geoip.country eq \"US\"\nip.geoip.continent eq \"EU\"\n\n// Bot detection (requires Bot Management)\ncf.bot_management.score lt 30\n\n// Method\nhttp.request.method eq \"POST\"\nhttp.request.method in {\"POST\" \"PUT\" \"PATCH\"}\n\n// Combine with logical operators\nhttp.host eq \"example.com\" and starts_with(http.request.uri.path, \"/api/\")\nip.geoip.country eq \"US\" or ip.geoip.country eq \"CA\"\nnot http.headers[\"user-agent\"] contains \"bot\"\n```\n\n### Expression Functions\n\n| Function | Example | Description |\n|----------|---------|-------------|\n| `starts_with()` | `starts_with(http.request.uri.path, \"/api/\")` | Check prefix |\n| `ends_with()` | `ends_with(http.request.uri.path, \".json\")` | Check suffix |\n| `contains()` | `contains(http.headers[\"user-agent\"], \"Mobile\")` | Check substring |\n| `matches()` | `matches(http.request.uri.path, \"^/api/\")` | Regex match |\n| `lower()` | `lower(http.host) eq \"example.com\"` | Convert to lowercase |\n| `upper()` | `upper(http.headers[\"x-api-key\"])` | Convert to uppercase |\n| `len()` | `len(http.request.uri.path) gt 100` | String length |\n\n## Deployment Workflow\n\n### Development\n1. Write snippet code locally\n2. Test syntax with `node snippet.js` or TypeScript compiler\n3. Deploy to Dashboard or use API with `Save as Draft`\n4. Test with Preview/HTTP tabs in Dashboard\n5. Enable rule when ready\n\n### Production\n1. Store snippet code in version control\n2. Use Terraform/Pulumi for reproducible deployments\n3. Deploy to staging zone first\n4. Test with real traffic (use low-traffic subdomain)\n5. Apply to production zone\n6. Monitor with Analytics/Logpush\n\n## Limits & Requirements\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| Snippet size | 32 KB | Per snippet, compressed |\n| Snippet name | 64 chars | `a-z`, `0-9`, `_` only, immutable |\n| Snippets per zone | 20 | Soft limit, contact support for more |\n| Rules per zone | 20 | One rule per snippet typical |\n| Expression length | 4096 chars | Per rule expression |\n\n## Authentication\n\n### API Token (Recommended)\n```bash\n# Create token at: https://dash.cloudflare.com/profile/api-tokens\n# Required permissions: Zone.Snippets:Edit, Zone.Rules:Edit\nexport CLOUDFLARE_API_TOKEN=\"your_token_here\"\n```\n\n### API Key (Legacy)\n```bash\nexport CLOUDFLARE_EMAIL=\"your@email.com\"\nexport CLOUDFLARE_API_KEY=\"your_global_api_key\"\n``` " }, { "path": "skills/.curated/cloudflare-deploy/references/snippets/gotchas.md", "content": "# Gotchas & Best Practices\n\n## Common Errors\n\n### 1000: \"Snippet execution failed\"\nRuntime error or syntax error. Wrap code in try/catch:\n```javascript\ntry { return await fetch(request); }\ncatch (error) { return new Response(`Error: ${error.message}`, { status: 500 }); }\n```\n\n### 1100: \"Exceeded execution limit\"\nCode takes >5ms CPU. Simplify logic or move to Workers.\n\n### 1201: \"Multiple origin fetches\"\nCall `fetch(request)` exactly once:\n```javascript\n// ❌ Multiple origin fetches\nconst r1 = await fetch(request); const r2 = await fetch(request);\n// ✅ Single fetch, reuse response\nconst response = await fetch(request);\n```\n\n### 1202: \"Subrequest limit exceeded\"\nPro: 2 subrequests, Business/Enterprise: 5. Reduce fetch calls.\n\n### \"Cannot set property on immutable object\"\nClone before modifying:\n```javascript\nconst modifiedRequest = new Request(request);\nmodifiedRequest.headers.set(\"X-Custom\", \"value\");\n```\n\n### \"caches is not defined\"\nCache API NOT available in Snippets. Use Workers.\n\n### \"Module not found\"\nSnippets don't support `import`. Use inline code or Workers.\n\n## Best Practices\n\n### Performance\n- Keep code <10KB (32KB limit)\n- Optimize for 5ms CPU\n- Clone only when modifying\n- Minimize subrequests\n\n### Security\n- Validate all inputs\n- Use Web Crypto API for hashing\n- Sanitize headers before origin\n- Don't log secrets\n\n### Debugging\n```javascript\nnewResponse.headers.set(\"X-Debug-Country\", request.cf.country);\n```\n```bash\ncurl -H \"X-Test: true\" https://example.com -v\n```\n\n## Available APIs\n\n**✅ Available:** `fetch()`, `Request`, `Response`, `Headers`, `URL`, `crypto.subtle`, `crypto.randomUUID()`, `atob()`/`btoa()`, `JSON`\n\n**❌ NOT Available:** `caches`, `KV`, `D1`, `R2`, `Durable Objects`, `WebSocket`, `HTMLRewriter`, `import`, Node.js APIs\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Snippet size | 32KB |\n| Execution time | 5ms CPU |\n| Subrequests (Pro/Biz) | 2/5 |\n| Snippets/zone | 20 |\n\n## Performance Benchmarks\n\n| Operation | Time |\n|-----------|------|\n| Header set | <0.1ms |\n| URL parsing | <0.2ms |\n| fetch() | 1-3ms |\n| SHA-256 | 0.5-1ms |\n\n**Migrate to Workers when:** >5ms needed, >5 subrequests, need storage (KV/D1/R2), need npm packages, >32KB code\n" }, { "path": "skills/.curated/cloudflare-deploy/references/snippets/patterns.md", "content": "# Snippets Patterns\n\n## Security Headers\n\n```javascript\nexport default {\n async fetch(request) {\n const response = await fetch(request);\n const newResponse = new Response(response.body, response);\n newResponse.headers.set(\"X-Frame-Options\", \"DENY\");\n newResponse.headers.set(\"X-Content-Type-Options\", \"nosniff\");\n newResponse.headers.delete(\"X-Powered-By\");\n return newResponse;\n }\n}\n```\n\n**Rule:** `true` (all requests)\n\n## Geo-Based Routing\n\n```javascript\nexport default {\n async fetch(request) {\n const country = request.cf.country;\n if ([\"GB\", \"DE\", \"FR\"].includes(country)) {\n const url = new URL(request.url);\n url.hostname = url.hostname.replace(\".com\", \".eu\");\n return Response.redirect(url.toString(), 302);\n }\n return fetch(request);\n }\n}\n```\n\n## A/B Testing\n\n```javascript\nexport default {\n async fetch(request) {\n const cookies = request.headers.get(\"Cookie\") || \"\";\n let variant = cookies.match(/ab_test=([AB])/)?.[1] || (Math.random() < 0.5 ? \"A\" : \"B\");\n \n const req = new Request(request);\n req.headers.set(\"X-Variant\", variant);\n const response = await fetch(req);\n \n if (!cookies.includes(\"ab_test=\")) {\n const newResponse = new Response(response.body, response);\n newResponse.headers.append(\"Set-Cookie\", `ab_test=${variant}; Path=/; Secure`);\n return newResponse;\n }\n return response;\n }\n}\n```\n\n## Bot Detection\n\n```javascript\nexport default {\n async fetch(request) {\n const botScore = request.cf.botManagement?.score;\n if (botScore && botScore < 30) return new Response(\"Denied\", { status: 403 });\n return fetch(request);\n }\n}\n```\n\n**Requires:** Bot Management plan\n\n## API Auth Header Injection\n\n```javascript\nexport default {\n async fetch(request) {\n if (new URL(request.url).pathname.startsWith(\"/api/\")) {\n const req = new Request(request);\n req.headers.set(\"X-Internal-Auth\", \"secret_token\");\n req.headers.delete(\"Authorization\");\n return fetch(req);\n }\n return fetch(request);\n }\n}\n```\n\n## CORS Headers\n\n```javascript\nexport default {\n async fetch(request) {\n if (request.method === \"OPTIONS\") {\n return new Response(null, {\n status: 204,\n headers: {\n \"Access-Control-Allow-Origin\": \"*\",\n \"Access-Control-Allow-Methods\": \"GET, POST, PUT, DELETE\",\n \"Access-Control-Allow-Headers\": \"Content-Type, Authorization\"\n }\n });\n }\n const response = await fetch(request);\n const newResponse = new Response(response.body, response);\n newResponse.headers.set(\"Access-Control-Allow-Origin\", \"*\");\n return newResponse;\n }\n}\n```\n\n## Maintenance Mode\n\n```javascript\nexport default {\n async fetch(request) {\n if (request.headers.get(\"X-Bypass-Token\") === \"admin\") return fetch(request);\n return new Response(\"

Maintenance

\", {\n status: 503,\n headers: { \"Content-Type\": \"text/html\", \"Retry-After\": \"3600\" }\n });\n }\n}\n```\n\n## Pattern Selection\n\n| Pattern | Complexity | Use Case |\n|---------|-----------|----------|\n| Security Headers | Low | All sites |\n| Geo-Routing | Low | Regional content |\n| A/B Testing | Medium | Experiments |\n| Bot Detection | Medium | Requires Bot Management |\n| API Auth | Low | Backend protection |\n| CORS | Low | API endpoints |\n| Maintenance | Low | Deployments |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/spectrum/README.md", "content": "# Cloudflare Spectrum Skill Reference\n\n## Overview\n\nCloudflare Spectrum provides security and acceleration for ANY TCP or UDP-based application. It's a global Layer 4 (L4) reverse proxy running on Cloudflare's edge nodes that routes MQTT, email, file transfer, version control, games, and more through Cloudflare to mask origins and protect from DDoS attacks.\n\n**When to Use Spectrum**: When your protocol isn't HTTP/HTTPS (use Cloudflare proxy for HTTP). Spectrum handles everything else: SSH, gaming, databases, MQTT, SMTP, RDP, custom protocols.\n\n## Plan Capabilities\n\n| Capability | Pro/Business | Enterprise |\n|------------|--------------|------------|\n| TCP protocols | Selected ports only | All ports (1-65535) |\n| UDP protocols | Selected ports only | All ports (1-65535) |\n| Port ranges | ❌ | ✅ |\n| Argo Smart Routing | ✅ | ✅ |\n| IP Firewall | ✅ | ✅ |\n| Load balancer origins | ✅ | ✅ |\n\n## Decision Tree\n\n**What are you trying to do?**\n\n1. **Create/manage Spectrum app**\n - Via Dashboard → See [Cloudflare Dashboard](https://dash.cloudflare.com)\n - Via API → See [api.md](api.md) - REST endpoints\n - Via SDK → See [api.md](api.md) - TypeScript/Python/Go examples\n - Via IaC → See [configuration.md](configuration.md) - Terraform/Pulumi\n\n2. **Protect specific protocol**\n - SSH → See [patterns.md](patterns.md#1-ssh-server-protection)\n - Gaming (Minecraft, etc) → See [patterns.md](patterns.md#2-game-server)\n - MQTT/IoT → See [patterns.md](patterns.md#3-mqtt-broker)\n - SMTP/Email → See [patterns.md](patterns.md#4-smtp-relay)\n - Database → See [patterns.md](patterns.md#5-database-proxy)\n - RDP → See [patterns.md](patterns.md#6-rdp-remote-desktop)\n\n3. **Choose origin type**\n - Direct IP (single server) → See [configuration.md](configuration.md#direct-ip-origin)\n - CNAME (hostname) → See [configuration.md](configuration.md#cname-origin)\n - Load balancer (HA/failover) → See [configuration.md](configuration.md#load-balancer-origin)\n\n## Reading Order\n\n1. Start with [patterns.md](patterns.md) for your specific protocol\n2. Then [configuration.md](configuration.md) for your origin type\n3. Check [gotchas.md](gotchas.md) before going to production\n4. Use [api.md](api.md) for programmatic access\n\n## See Also\n\n- [Cloudflare Docs](https://developers.cloudflare.com/spectrum/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/spectrum/api.md", "content": "## REST API Endpoints\n\n```\nGET /zones/{zone_id}/spectrum/apps # List apps\nPOST /zones/{zone_id}/spectrum/apps # Create app\nGET /zones/{zone_id}/spectrum/apps/{app_id} # Get app\nPUT /zones/{zone_id}/spectrum/apps/{app_id} # Update app\nDELETE /zones/{zone_id}/spectrum/apps/{app_id} # Delete app\n\nGET /zones/{zone_id}/spectrum/analytics/aggregate/current\nGET /zones/{zone_id}/spectrum/analytics/events/bytime\nGET /zones/{zone_id}/spectrum/analytics/events/summary\n```\n\n## Request/Response Schemas\n\n### CreateSpectrumAppRequest\n\n```typescript\ninterface CreateSpectrumAppRequest {\n protocol: string; // \"tcp/22\", \"udp/53\"\n dns: {\n type: \"CNAME\" | \"ADDRESS\";\n name: string; // \"ssh.example.com\"\n };\n origin_direct?: string[]; // [\"tcp://192.0.2.1:22\"]\n origin_dns?: { name: string }; // {\"name\": \"origin.example.com\"}\n origin_port?: number | { start: number; end: number };\n proxy_protocol?: \"off\" | \"v1\" | \"v2\" | \"simple\";\n ip_firewall?: boolean;\n tls?: \"off\" | \"flexible\" | \"full\" | \"strict\";\n edge_ips?: {\n type: \"dynamic\" | \"static\";\n connectivity: \"all\" | \"ipv4\" | \"ipv6\";\n };\n traffic_type?: \"direct\" | \"http\" | \"https\";\n argo_smart_routing?: boolean;\n}\n```\n\n### SpectrumApp Response\n\n```typescript\ninterface SpectrumApp {\n id: string;\n protocol: string;\n dns: { type: string; name: string };\n origin_direct?: string[];\n origin_dns?: { name: string };\n origin_port?: number | { start: number; end: number };\n proxy_protocol: string;\n ip_firewall: boolean;\n tls: string;\n edge_ips: { type: string; connectivity: string; ips?: string[] };\n argo_smart_routing: boolean;\n created_on: string;\n modified_on: string;\n}\n```\n\n## TypeScript SDK\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });\n\n// Create\nconst app = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/22',\n dns: { type: 'CNAME', name: 'ssh.example.com' },\n origin_direct: ['tcp://192.0.2.1:22'],\n ip_firewall: true,\n tls: 'off',\n});\n\n// List\nconst apps = await client.spectrum.apps.list({ zone_id: 'your-zone-id' });\n\n// Get\nconst appDetails = await client.spectrum.apps.get({ zone_id: 'your-zone-id', app_id: app.id });\n\n// Update\nawait client.spectrum.apps.update({ zone_id: 'your-zone-id', app_id: app.id, tls: 'full' });\n\n// Delete\nawait client.spectrum.apps.delete({ zone_id: 'your-zone-id', app_id: app.id });\n\n// Analytics\nconst analytics = await client.spectrum.analytics.aggregate({\n zone_id: 'your-zone-id',\n metrics: ['bytesIngress', 'bytesEgress'],\n since: new Date(Date.now() - 3600000).toISOString(),\n});\n```\n\n## Python SDK\n\n```python\nfrom cloudflare import Cloudflare\n\nclient = Cloudflare(api_token=\"your-api-token\")\n\n# Create\napp = client.spectrum.apps.create(\n zone_id=\"your-zone-id\",\n protocol=\"tcp/22\",\n dns={\"type\": \"CNAME\", \"name\": \"ssh.example.com\"},\n origin_direct=[\"tcp://192.0.2.1:22\"],\n ip_firewall=True,\n tls=\"off\",\n)\n\n# List\napps = client.spectrum.apps.list(zone_id=\"your-zone-id\")\n\n# Get\napp_details = client.spectrum.apps.get(zone_id=\"your-zone-id\", app_id=app.id)\n\n# Update\nclient.spectrum.apps.update(zone_id=\"your-zone-id\", app_id=app.id, tls=\"full\")\n\n# Delete\nclient.spectrum.apps.delete(zone_id=\"your-zone-id\", app_id=app.id)\n\n# Analytics\nanalytics = client.spectrum.analytics.aggregate(\n zone_id=\"your-zone-id\",\n metrics=[\"bytesIngress\", \"bytesEgress\"],\n since=datetime.now() - timedelta(hours=1),\n)\n```\n\n## Go SDK\n\n```go\nimport \"github.com/cloudflare/cloudflare-go\"\n\napi, _ := cloudflare.NewWithAPIToken(\"your-api-token\")\n\n// Create\napp, _ := api.CreateSpectrumApplication(ctx, \"zone-id\", cloudflare.SpectrumApplication{\n Protocol: \"tcp/22\",\n DNS: cloudflare.SpectrumApplicationDNS{Type: \"CNAME\", Name: \"ssh.example.com\"},\n OriginDirect: []string{\"tcp://192.0.2.1:22\"},\n IPFirewall: true,\n ArgoSmartRouting: true,\n})\n\n// List\napps, _ := api.SpectrumApplications(ctx, \"zone-id\")\n\n// Delete\n_ = api.DeleteSpectrumApplication(ctx, \"zone-id\", app.ID)\n```\n\n## Analytics API\n\n**Metrics:**\n- `bytesIngress` - Bytes received from clients\n- `bytesEgress` - Bytes sent to clients\n- `count` - Number of connections\n- `duration` - Connection duration (seconds)\n\n**Dimensions:**\n- `event` - Connection event type\n- `appID` - Spectrum application ID\n- `coloName` - Datacenter name\n- `ipVersion` - IPv4 or IPv6\n\n**Example:**\n```bash\ncurl \"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/spectrum/analytics/aggregate/current?metrics=bytesIngress,bytesEgress,count&dimensions=appID\" \\\n --header \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\"\n```\n\n## See Also\n\n- [configuration.md](configuration.md) - Terraform/Pulumi\n- [patterns.md](patterns.md) - Protocol examples\n" }, { "path": "skills/.curated/cloudflare-deploy/references/spectrum/configuration.md", "content": "## Origin Types\n\n### Direct IP Origin\n\nUse when origin is a single server with static IP.\n\n**TypeScript SDK:**\n```typescript\nconst app = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/22',\n dns: { type: 'CNAME', name: 'ssh.example.com' },\n origin_direct: ['tcp://192.0.2.1:22'],\n ip_firewall: true,\n tls: 'off',\n});\n```\n\n**Terraform:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"ssh\" {\n zone_id = var.zone_id\n protocol = \"tcp/22\"\n\n dns {\n type = \"CNAME\"\n name = \"ssh.example.com\"\n }\n\n origin_direct = [\"tcp://192.0.2.1:22\"]\n ip_firewall = true\n tls = \"off\"\n argo_smart_routing = true\n}\n```\n\n### CNAME Origin\n\nUse when origin is a hostname (not static IP). Spectrum resolves DNS dynamically.\n\n**TypeScript SDK:**\n```typescript\nconst app = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/3306',\n dns: { type: 'CNAME', name: 'db.example.com' },\n origin_dns: { name: 'db-primary.internal.example.com' },\n origin_port: 3306,\n tls: 'full',\n});\n```\n\n**Terraform:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"database\" {\n zone_id = var.zone_id\n protocol = \"tcp/3306\"\n\n dns {\n type = \"CNAME\"\n name = \"db.example.com\"\n }\n\n origin_dns {\n name = \"db-primary.internal.example.com\"\n }\n\n origin_port = 3306\n tls = \"full\"\n argo_smart_routing = true\n}\n```\n\n### Load Balancer Origin\n\nUse for high availability and failover.\n\n**Terraform:**\n```hcl\nresource \"cloudflare_load_balancer\" \"game_lb\" {\n zone_id = var.zone_id\n name = \"game-lb.example.com\"\n default_pool_ids = [cloudflare_load_balancer_pool.game_pool.id]\n}\n\nresource \"cloudflare_load_balancer_pool\" \"game_pool\" {\n name = \"game-primary\"\n origins { name = \"game-1\"; address = \"192.0.2.1\" }\n monitor = cloudflare_load_balancer_monitor.tcp_monitor.id\n}\n\nresource \"cloudflare_load_balancer_monitor\" \"tcp_monitor\" {\n type = \"tcp\"; port = 25565; interval = 60; timeout = 5\n}\n\nresource \"cloudflare_spectrum_application\" \"game\" {\n zone_id = var.zone_id\n protocol = \"tcp/25565\"\n dns { type = \"CNAME\"; name = \"game.example.com\" }\n origin_dns { name = cloudflare_load_balancer.game_lb.name }\n origin_port = 25565\n}\n```\n\n## TLS Configuration\n\n| Mode | Description | Use Case | Origin Cert |\n|------|-------------|----------|-------------|\n| `off` | No TLS | Non-encrypted (SSH, gaming) | No |\n| `flexible` | TLS client→CF, plain CF→origin | Testing | No |\n| `full` | TLS end-to-end, self-signed OK | Production | Yes (any) |\n| `strict` | Full + valid cert verification | Max security | Yes (CA) |\n\n**Example:**\n```typescript\nconst app = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/3306',\n dns: { type: 'CNAME', name: 'db.example.com' },\n origin_direct: ['tcp://192.0.2.1:3306'],\n tls: 'strict', // Validates origin certificate\n});\n```\n\n## Proxy Protocol\n\nForwards real client IP to origin. Origin must support parsing.\n\n| Version | Protocol | Use Case |\n|---------|----------|----------|\n| `off` | - | Origin doesn't need client IP |\n| `v1` | TCP | Most TCP apps (SSH, databases) |\n| `v2` | TCP | High-performance TCP |\n| `simple` | UDP | UDP applications |\n\n**Compatibility:**\n- **v1**: HAProxy, nginx, SSH, most databases\n- **v2**: HAProxy 1.5+, nginx 1.11+\n- **simple**: Cloudflare-specific UDP format\n\n**Enable:**\n```typescript\nconst app = await client.spectrum.apps.create({\n // ...\n proxy_protocol: 'v1', // Origin must parse PROXY header\n});\n```\n\n**Origin Config (nginx):**\n```nginx\nstream {\n server {\n listen 22 proxy_protocol;\n proxy_pass backend:22;\n }\n}\n```\n\n## IP Access Rules\n\nEnable `ip_firewall: true` then configure zone-level firewall rules.\n\n```typescript\nconst app = await client.spectrum.apps.create({\n // ...\n ip_firewall: true, // Applies zone firewall rules\n});\n```\n\n## Port Ranges (Enterprise Only)\n\n```hcl\nresource \"cloudflare_spectrum_application\" \"game_cluster\" {\n zone_id = var.zone_id\n protocol = \"tcp/25565-25575\"\n\n dns {\n type = \"CNAME\"\n name = \"games.example.com\"\n }\n\n origin_direct = [\"tcp://192.0.2.1\"]\n \n origin_port {\n start = 25565\n end = 25575\n }\n}\n```\n\n## See Also\n\n- [patterns.md](patterns.md) - Protocol-specific examples\n- [api.md](api.md) - REST/SDK reference\n" }, { "path": "skills/.curated/cloudflare-deploy/references/spectrum/gotchas.md", "content": "## Common Issues\n\n### Connection Timeouts\n\n**Problem:** Connections fail or timeout \n**Cause:** Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS \n**Solution:**\n1. Verify origin firewall allows Cloudflare IP ranges\n2. Check origin service running on correct port\n3. Ensure DNS record is CNAME (not A/AAAA)\n4. Verify origin IP/hostname is correct\n\n```bash\n# Test connectivity\nnc -zv app.example.com 22\ndig app.example.com\n```\n\n### Client IP Showing Cloudflare IP\n\n**Problem:** Origin logs show Cloudflare IPs not real client IPs \n**Cause:** Proxy Protocol not enabled or origin not configured \n**Solution:**\n```typescript\n// Enable in Spectrum app\nconst app = await client.spectrum.apps.create({\n // ...\n proxy_protocol: 'v1', // TCP: v1/v2; UDP: simple\n});\n```\n\n**Origin config:**\n- **nginx**: `listen 22 proxy_protocol;`\n- **HAProxy**: `bind :22 accept-proxy`\n\n### TLS Errors\n\n**Problem:** TLS handshake failures, 525 errors \n**Cause:** TLS mode mismatch\n\n| Error | TLS Mode | Problem | Solution |\n|-------|----------|---------|----------|\n| Connection refused | `full`/`strict` | Origin not TLS | Use `tls: \"off\"` or enable TLS |\n| 525 cert invalid | `strict` | Self-signed cert | Use `tls: \"full\"` or valid cert |\n| Handshake timeout | `flexible` | Origin expects TLS | Use `tls: \"full\"` |\n\n**Debug:**\n```bash\nopenssl s_client -connect app.example.com:443 -showcerts\n```\n\n### SMTP Reverse DNS\n\n**Problem:** Email servers reject SMTP via Spectrum \n**Cause:** Spectrum IPs lack PTR (reverse DNS) records \n**Impact:** Many mail servers require valid rDNS for anti-spam\n\n**Solution:**\n- Outbound SMTP: NOT recommended through Spectrum\n- Inbound SMTP: Use Cloudflare Email Routing\n- Internal relay: Whitelist Spectrum IPs on destination\n\n### Proxy Protocol Compatibility\n\n**Problem:** Connection works but app behaves incorrectly \n**Cause:** Origin doesn't support Proxy Protocol\n\n**Solution:**\n1. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+)\n2. Test with `proxy_protocol: 'off'` first\n3. Configure origin to parse headers\n\n**nginx TCP:**\n```nginx\nstream {\n server {\n listen 22 proxy_protocol;\n proxy_pass backend:22;\n }\n}\n```\n\n**HAProxy:**\n```\nfrontend ft_ssh\n bind :22 accept-proxy\n```\n\n### Analytics Data Retention\n\n**Problem:** Historical data not available \n**Cause:** Retention varies by plan\n\n| Plan | Real-time | Historical |\n|------|-----------|------------|\n| Pro | Last hour | ❌ |\n| Business | Last hour | Limited |\n| Enterprise | Last hour | 90+ days |\n\n**Solution:** Query within retention window or export to external system\n\n### Enterprise-Only Features\n\n**Problem:** Feature unavailable/errors \n**Cause:** Requires Enterprise plan\n\n**Enterprise-only:**\n- Port ranges (`tcp/25565-25575`)\n- All TCP/UDP ports (Pro/Business: selected only)\n- Extended analytics retention\n- Advanced load balancing\n\n### IPv6 Considerations\n\n**Problem:** IPv6 clients can't connect or origin doesn't support IPv6 \n**Solution:** Configure `edge_ips.connectivity`\n\n```typescript\nconst app = await client.spectrum.apps.create({\n // ...\n edge_ips: {\n type: 'dynamic',\n connectivity: 'ipv4', // Options: 'all', 'ipv4', 'ipv6'\n },\n});\n```\n\n**Options:**\n- `all`: Dual-stack (default, requires origin support both)\n- `ipv4`: IPv4 only (use if origin lacks IPv6)\n- `ipv6`: IPv6 only (rare)\n\n## Limits\n\n| Resource | Pro/Business | Enterprise |\n|----------|--------------|------------|\n| Max apps | ~10-15 | 100+ |\n| Protocols | Selected | All TCP/UDP |\n| Port ranges | ❌ | ✅ |\n| Analytics | ~1 hour | 90+ days |\n\n## See Also\n\n- [patterns.md](patterns.md) - Protocol examples\n- [configuration.md](configuration.md) - TLS/Proxy setup\n" }, { "path": "skills/.curated/cloudflare-deploy/references/spectrum/patterns.md", "content": "## Common Use Cases\n\n### 1. SSH Server Protection\n\n**Terraform:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"ssh\" {\n zone_id = var.zone_id\n protocol = \"tcp/22\"\n\n dns {\n type = \"CNAME\"\n name = \"ssh.example.com\"\n }\n\n origin_direct = [\"tcp://10.0.1.5:22\"]\n ip_firewall = true\n argo_smart_routing = true\n}\n```\n\n**Benefits:** Hide origin IP, DDoS protection, IP firewall, Argo reduces latency\n\n### 2. Game Server\n\n**TypeScript (Minecraft):**\n```typescript\nconst app = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/25565',\n dns: { type: 'CNAME', name: 'mc.example.com' },\n origin_direct: ['tcp://192.168.1.10:25565'],\n proxy_protocol: 'v1', // Preserves player IPs\n argo_smart_routing: true,\n});\n```\n\n**Benefits:** DDoS protection, hide origin IP, Proxy Protocol for player IPs/bans, Argo reduces latency\n\n### 3. MQTT Broker\n\nIoT device communication.\n\n**TypeScript:**\n```typescript\nconst mqttApp = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/8883', // Use 1883 for plain MQTT\n dns: { type: 'CNAME', name: 'mqtt.example.com' },\n origin_direct: ['tcp://mqtt-broker.internal:8883'],\n tls: 'full', // Use 'off' for plain MQTT\n});\n```\n\n**Benefits:** DDoS protection, hide broker IP, TLS termination at edge\n\n### 4. SMTP Relay\n\nEmail submission (port 587). **WARNING**: See [gotchas.md](gotchas.md#smtp-reverse-dns)\n\n**Terraform:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"smtp\" {\n zone_id = var.zone_id\n protocol = \"tcp/587\"\n\n dns {\n type = \"CNAME\"\n name = \"smtp.example.com\"\n }\n\n origin_direct = [\"tcp://mail-server.internal:587\"]\n tls = \"full\" # STARTTLS support\n}\n```\n\n**Limitations:**\n- Spectrum IPs lack reverse DNS (PTR records)\n- Many mail servers reject without valid rDNS\n- Best for internal/trusted relay only\n\n### 5. Database Proxy\n\nMySQL/PostgreSQL. **Use with caution** - security critical.\n\n**PostgreSQL:**\n```typescript\nconst postgresApp = await client.spectrum.apps.create({\n zone_id: 'your-zone-id',\n protocol: 'tcp/5432',\n dns: { type: 'CNAME', name: 'postgres.example.com' },\n origin_dns: { name: 'db-primary.internal.example.com' },\n origin_port: 5432,\n tls: 'strict', // REQUIRED\n ip_firewall: true, // REQUIRED\n});\n```\n\n**MySQL:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"mysql\" {\n zone_id = var.zone_id\n protocol = \"tcp/3306\"\n\n dns {\n type = \"CNAME\"\n name = \"mysql.example.com\"\n }\n\n origin_dns {\n name = \"mysql-primary.internal.example.com\"\n }\n\n origin_port = 3306\n tls = \"strict\"\n ip_firewall = true\n}\n```\n\n**Security:**\n- ALWAYS use `tls: \"strict\"`\n- ALWAYS use `ip_firewall: true`\n- Restrict to known IPs via zone firewall\n- Use strong DB authentication\n- Consider VPN or Cloudflare Access instead\n\n### 6. RDP (Remote Desktop)\n\n**Requires IP firewall.**\n\n**Terraform:**\n```hcl\nresource \"cloudflare_spectrum_application\" \"rdp\" {\n zone_id = var.zone_id\n protocol = \"tcp/3389\"\n\n dns {\n type = \"CNAME\"\n name = \"rdp.example.com\"\n }\n\n origin_direct = [\"tcp://windows-server.internal:3389\"]\n tls = \"off\" # RDP has own encryption\n ip_firewall = true # REQUIRED\n}\n```\n\n**Security:** ALWAYS `ip_firewall: true`, whitelist admin IPs, RDP is DDoS/brute-force target\n\n### 7. Multi-Origin Failover\n\nHigh availability with load balancer.\n\n**Terraform:**\n```hcl\nresource \"cloudflare_load_balancer\" \"database_lb\" {\n zone_id = var.zone_id\n name = \"db-lb.example.com\"\n default_pool_ids = [cloudflare_load_balancer_pool.db_primary.id]\n fallback_pool_id = cloudflare_load_balancer_pool.db_secondary.id\n}\n\nresource \"cloudflare_load_balancer_pool\" \"db_primary\" {\n name = \"db-primary-pool\"\n origins { name = \"db-1\"; address = \"192.0.2.1\" }\n monitor = cloudflare_load_balancer_monitor.postgres_monitor.id\n}\n\nresource \"cloudflare_load_balancer_pool\" \"db_secondary\" {\n name = \"db-secondary-pool\"\n origins { name = \"db-2\"; address = \"192.0.2.2\" }\n monitor = cloudflare_load_balancer_monitor.postgres_monitor.id\n}\n\nresource \"cloudflare_load_balancer_monitor\" \"postgres_monitor\" {\n type = \"tcp\"; port = 5432; interval = 30; timeout = 5\n}\n\nresource \"cloudflare_spectrum_application\" \"postgres_ha\" {\n zone_id = var.zone_id\n protocol = \"tcp/5432\"\n dns { type = \"CNAME\"; name = \"postgres.example.com\" }\n origin_dns { name = cloudflare_load_balancer.database_lb.name }\n origin_port = 5432\n tls = \"strict\"\n ip_firewall = true\n}\n```\n\n**Benefits:** Automatic failover, health monitoring, traffic distribution, zero-downtime deployments\n\n## See Also\n\n- [configuration.md](configuration.md) - Origin type setup\n- [gotchas.md](gotchas.md) - Protocol limitations\n- [api.md](api.md) - SDK reference\n" }, { "path": "skills/.curated/cloudflare-deploy/references/static-assets/README.md", "content": "# Cloudflare Static Assets Skill Reference\n\nExpert guidance for deploying and configuring static assets with Cloudflare Workers. This skill covers configuration patterns, routing architectures, asset binding usage, and best practices for SPAs, SSG sites, and full-stack applications.\n\n## Quick Start\n\n```jsonc\n// wrangler.jsonc\n{\n \"name\": \"my-app\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \"assets\": {\n \"directory\": \"./dist\"\n }\n}\n```\n\n```typescript\n// src/index.ts\nexport default {\n async fetch(request: Request, env: Env): Promise {\n return env.ASSETS.fetch(request);\n }\n};\n```\n\nDeploy: `wrangler deploy`\n\n## When to Use Workers Static Assets vs Pages\n\n| Factor | Workers Static Assets | Cloudflare Pages |\n|--------|----------------------|------------------|\n| **Use case** | Hybrid apps (static + dynamic API) | Static sites, SSG |\n| **Worker control** | Full control over routing | Limited (Functions) |\n| **Configuration** | Code-first, flexible | Git-based, opinionated |\n| **Dynamic routing** | Worker-first patterns | Functions (_functions/) |\n| **Best for** | Full-stack apps, SPAs with APIs | Jamstack, static docs |\n\n**Decision tree:**\n\n- Need custom routing logic? → Workers Static Assets\n- Pure static site or SSG? → Pages\n- API routes + SPA? → Workers Static Assets\n- Framework (Next, Nuxt, Remix)? → Pages\n\n## Reading Order\n\n1. **configuration.md** - Setup, wrangler.jsonc options, routing patterns\n2. **api.md** - ASSETS binding API, request/response handling\n3. **patterns.md** - Common patterns (SPA, API routes, auth, A/B testing)\n4. **gotchas.md** - Limits, errors, performance tips\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, configuration\n- **[api.md](api.md)** - API endpoints, methods, interfaces\n- **[patterns.md](patterns.md)** - Common patterns, use cases, examples\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations\n\n## See Also\n\n- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)\n- [Static Assets Docs](https://developers.cloudflare.com/workers/static-assets/)\n- [Cloudflare Pages](https://developers.cloudflare.com/pages/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/static-assets/api.md", "content": "# API Reference\n\n## ASSETS Binding\n\nThe `ASSETS` binding provides access to static assets via the `Fetcher` interface.\n\n### Type Definition\n\n```typescript\ninterface Env {\n ASSETS: Fetcher;\n}\n\ninterface Fetcher {\n fetch(input: RequestInfo | URL, init?: RequestInit): Promise;\n}\n```\n\n### Method Signatures\n\n```typescript\n// 1. Forward entire request\nawait env.ASSETS.fetch(request);\n\n// 2. String path (hostname ignored, only path matters)\nawait env.ASSETS.fetch(\"https://any-host/path/to/asset.png\");\n\n// 3. URL object\nawait env.ASSETS.fetch(new URL(\"/index.html\", request.url));\n\n// 4. Constructed Request object\nawait env.ASSETS.fetch(new Request(new URL(\"/logo.png\", request.url), {\n method: \"GET\",\n headers: request.headers\n}));\n```\n\n**Key behaviors:**\n\n- Host/origin is ignored for string/URL inputs (only path is used)\n- Method must be GET (others return 405)\n- Request headers pass through (affects response)\n- Returns standard `Response` object\n\n## Request Handling\n\n### Path Resolution\n\n```typescript\n// All resolve to same asset:\nenv.ASSETS.fetch(\"https://example.com/logo.png\")\nenv.ASSETS.fetch(\"https://ignored.host/logo.png\")\nenv.ASSETS.fetch(\"/logo.png\")\n```\n\nAssets are resolved relative to configured `assets.directory`.\n\n### Headers\n\nRequest headers that affect response:\n\n| Header | Effect |\n|--------|--------|\n| `Accept-Encoding` | Controls compression (gzip, brotli) |\n| `Range` | Enables partial content (206 responses) |\n| `If-None-Match` | Conditional request via ETag |\n| `If-Modified-Since` | Conditional request via modification date |\n\nCustom headers pass through but don't affect asset serving.\n\n### Method Support\n\n| Method | Supported | Response |\n|--------|-----------|----------|\n| `GET` | ✅ Yes | Asset content |\n| `HEAD` | ✅ Yes | Headers only, no body |\n| `POST`, `PUT`, etc. | ❌ No | 405 Method Not Allowed |\n\n## Response Behavior\n\n### Content-Type Inference\n\nAutomatically set based on file extension:\n\n| Extension | Content-Type |\n|-----------|--------------|\n| `.html` | `text/html; charset=utf-8` |\n| `.css` | `text/css` |\n| `.js` | `application/javascript` |\n| `.json` | `application/json` |\n| `.png` | `image/png` |\n| `.jpg`, `.jpeg` | `image/jpeg` |\n| `.svg` | `image/svg+xml` |\n| `.woff2` | `font/woff2` |\n\n### Default Headers\n\nResponses include:\n\n```\nContent-Type: \nETag: \"\"\nCache-Control: public, max-age=3600\nContent-Encoding: br (if supported and beneficial)\n```\n\n**Cache-Control defaults:**\n\n- 1 hour (`max-age=3600`) for most assets\n- Override via Worker response transformation (see patterns.md:27-35)\n\n### Compression\n\nAutomatic compression based on `Accept-Encoding`:\n\n- **Brotli** (`br`): Preferred, best compression\n- **Gzip** (`gzip`): Fallback\n- **None**: If client doesn't support or asset too small\n\n### ETag Generation\n\nETags are content-based hashes:\n\n```\nETag: \"a3b2c1d4e5f6...\"\n```\n\nUsed for conditional requests (`If-None-Match`). Returns `304 Not Modified` if match.\n\n## Error Responses\n\n| Status | Condition | Behavior |\n|--------|-----------|----------|\n| `404` | Asset not found | Body depends on `not_found_handling` config |\n| `405` | Non-GET/HEAD method | `{ \"error\": \"Method not allowed\" }` |\n| `416` | Invalid Range header | Range not satisfiable |\n\n### 404 Handling\n\nDepends on configuration (see configuration.md:45-52):\n\n```typescript\n// not_found_handling: \"single-page-application\"\n// Returns /index.html with 200 status\n\n// not_found_handling: \"404-page\"\n// Returns /404.html if exists, else 404 response\n\n// not_found_handling: \"none\"\n// Returns 404 response\n```\n\n## Advanced Usage\n\n### Modifying Responses\n\n```typescript\nconst response = await env.ASSETS.fetch(request);\n\n// Clone and modify\nreturn new Response(response.body, {\n status: response.status,\n headers: {\n ...Object.fromEntries(response.headers),\n 'Cache-Control': 'public, max-age=31536000',\n 'X-Custom': 'value'\n }\n});\n```\n\nSee patterns.md:27-35 for full example.\n\n### Error Handling\n\n```typescript\nconst response = await env.ASSETS.fetch(request);\n\nif (!response.ok) {\n // Asset not found or error\n return new Response('Custom error page', { status: 404 });\n}\n\nreturn response;\n```\n\n### Conditional Serving\n\n```typescript\nconst url = new URL(request.url);\n\n// Serve different assets based on conditions\nif (url.pathname === '/') {\n return env.ASSETS.fetch('/index.html');\n}\n\nreturn env.ASSETS.fetch(request);\n```\n\nSee patterns.md for complete patterns.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/static-assets/configuration.md", "content": "## Configuration\n\n### Basic Setup\n\nMinimal configuration requires only `assets.directory`:\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \"assets\": {\n \"directory\": \"./dist\"\n }\n}\n```\n\n### Full Configuration Options\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \"assets\": {\n \"directory\": \"./dist\",\n \"binding\": \"ASSETS\",\n \"not_found_handling\": \"single-page-application\",\n \"html_handling\": \"auto-trailing-slash\",\n \"run_worker_first\": [\"/api/*\", \"!/api/docs/*\"]\n }\n}\n```\n\n**Configuration keys:**\n\n- `directory` (string, required): Path to assets folder (e.g. `./dist`, `./public`, `./build`)\n- `binding` (string, optional): Name to access assets in Worker code (e.g. `env.ASSETS`). Default: `\"ASSETS\"`\n- `not_found_handling` (string, optional): Behavior when asset not found\n - `\"single-page-application\"`: Serve `/index.html` for non-asset paths (default for SPAs)\n - `\"404-page\"`: Serve `/404.html` if present, otherwise 404\n - `\"none\"`: Return 404 for missing assets\n- `html_handling` (string, optional): URL trailing slash behavior\n- `run_worker_first` (boolean | string[], optional): Routes that invoke Worker before checking assets\n\n### not_found_handling Modes\n\n| Mode | Behavior | Use Case |\n|------|----------|----------|\n| `\"single-page-application\"` | Serve `/index.html` for non-asset requests | React, Vue, Angular SPAs |\n| `\"404-page\"` | Serve `/404.html` if exists, else 404 | Static sites with custom error page |\n| `\"none\"` | Return 404 for missing assets | API-first or custom routing |\n\n### html_handling Modes\n\nControls trailing slash behavior for HTML files:\n\n| Mode | `/page` | `/page/` | Use Case |\n|------|---------|----------|----------|\n| `\"auto-trailing-slash\"` | Redirect to `/page/` if `/page/index.html` exists | Serve `/page/index.html` | Default, SEO-friendly |\n| `\"force-trailing-slash\"` | Always redirect to `/page/` | Serve if exists | Consistent trailing slashes |\n| `\"drop-trailing-slash\"` | Serve if exists | Redirect to `/page` | Cleaner URLs |\n| `\"none\"` | No modification | No modification | Custom routing logic |\n\n**Default:** `\"auto-trailing-slash\"`\n\n### run_worker_first Configuration\n\nControls which requests invoke Worker before checking assets.\n\n**Boolean syntax:**\n\n```jsonc\n{\n \"assets\": {\n \"run_worker_first\": true // ALL requests invoke Worker\n }\n}\n```\n\n**Array syntax (recommended):**\n\n```jsonc\n{\n \"assets\": {\n \"run_worker_first\": [\n \"/api/*\", // Positive pattern: match API routes\n \"/admin/*\", // Match admin routes\n \"!/admin/assets/*\" // Negative pattern: exclude admin assets\n ]\n }\n}\n```\n\n**Pattern rules:**\n\n- Glob patterns: `*` (any chars), `**` (any path segments)\n- Negative patterns: Prefix with `!` to exclude\n- Precedence: Negative patterns override positive patterns\n- Default: `false` (assets served directly)\n\n**Decision guidance:**\n\n- Use `true` for API-first apps (few static assets)\n- Use array patterns for hybrid apps (APIs + static assets)\n- Use `false` for static-first sites (minimal dynamic routes)\n\n### .assetsignore File\n\nExclude files from upload using `.assetsignore` (same syntax as `.gitignore`):\n\n```\n# .assetsignore\n_worker.js\n*.map\n*.md\nnode_modules/\n.git/\n```\n\n**Common patterns:**\n\n- `_worker.js` - Exclude Worker code from assets\n- `*.map` - Exclude source maps\n- `*.md` - Exclude markdown files\n- Development artifacts\n\n### Vite Plugin Integration\n\nFor Vite-based projects, use `@cloudflare/vite-plugin`:\n\n```typescript\n// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { cloudflare } from '@cloudflare/vite-plugin';\n\nexport default defineConfig({\n plugins: [\n cloudflare({\n assets: {\n directory: './dist',\n binding: 'ASSETS'\n }\n })\n ]\n});\n```\n\n**Features:**\n\n- Automatic asset detection during dev\n- Hot module replacement for assets\n- Production build integration\n- Requires: Wrangler 4.0.0+, `@cloudflare/vite-plugin` 1.0.0+\n\n### Key Compatibility Dates\n\n| Date | Feature | Impact |\n|------|---------|--------|\n| `2025-04-01` | Navigation request optimization | SPAs skip Worker for navigation, reducing costs |\n\nUse current date for new projects. See [Compatibility Dates](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) for full list.\n\n### Environment-Specific Configuration\n\nUse `wrangler.jsonc` environments for different configs:\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"assets\": { \"directory\": \"./dist\" },\n \"env\": {\n \"staging\": {\n \"assets\": {\n \"not_found_handling\": \"404-page\"\n }\n },\n \"production\": {\n \"assets\": {\n \"not_found_handling\": \"single-page-application\"\n }\n }\n }\n}\n```\n\nDeploy with: `wrangler deploy --env staging`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/static-assets/gotchas.md", "content": "## Best Practices\n\n### 1. Use Selective Worker-First Routing\n\nInstead of `run_worker_first = true`, use array patterns:\n\n```jsonc\n{\n \"assets\": {\n \"run_worker_first\": [\n \"/api/*\", // API routes\n \"/admin/*\", // Admin area\n \"!/admin/assets/*\" // Except admin assets\n ]\n }\n}\n```\n\n**Benefits:**\n- Reduces Worker invocations\n- Lowers costs\n- Improves asset delivery performance\n\n### 2. Leverage Navigation Request Optimization\n\nFor SPAs, use `compatibility_date = \"2025-04-01\"` or later:\n\n```jsonc\n{\n \"compatibility_date\": \"2025-04-01\",\n \"assets\": {\n \"not_found_handling\": \"single-page-application\"\n }\n}\n```\n\nNavigation requests skip Worker invocation, reducing costs.\n\n### 3. Type Safety with Bindings\n\nAlways type your environment:\n\n```typescript\ninterface Env {\n ASSETS: Fetcher;\n}\n```\n\n## Common Errors\n\n### \"Asset not found\"\n\n**Cause:** Asset not in assets directory, wrong path, or assets not deployed \n**Solution:** Verify asset exists, check path case-sensitivity, redeploy if needed\n\n### \"Worker not invoked for asset\"\n\n**Cause:** Asset served directly, `run_worker_first` not configured \n**Solution:** Configure `run_worker_first` patterns to include asset routes (see configuration.md:66-106)\n\n### \"429 Too Many Requests on free tier\"\n\n**Cause:** `run_worker_first` patterns invoke Worker for many requests, hitting free tier limits (100k req/day) \n**Solution:** Use more selective patterns with negative exclusions, or upgrade to paid plan\n\n### \"Smart Placement increases latency\"\n\n**Cause:** `run_worker_first=true` + Smart Placement routes all requests through single smart-placed location \n**Solution:** Use selective patterns (array syntax) or disable Smart Placement for asset-heavy apps\n\n### \"CF-Cache-Status header unreliable\"\n\n**Cause:** Header is probabilistically added for privacy reasons \n**Solution:** Don't rely on `CF-Cache-Status` for critical routing logic. Use other signals (ETag, age).\n\n### \"JWT expired during deployment\"\n\n**Cause:** Large asset deployments exceed JWT token lifetime \n**Solution:** Update to Wrangler 4.34.0+ (automatic token refresh), or reduce asset count\n\n### \"Cannot use 'assets' with 'site'\"\n\n**Cause:** Legacy `site` config conflicts with new `assets` config \n**Solution:** Migrate from `site` to `assets` (see configuration.md). Remove `site` key from wrangler.jsonc.\n\n### \"Assets not updating after deployment\"\n\n**Cause:** Browser or CDN cache serving old assets \n**Solution:** \n- Hard refresh browser (Cmd+Shift+R / Ctrl+F5)\n- Use cache-busting (hashed filenames)\n- Verify deployment completed: `wrangler tail`\n\n## Limits\n\n| Resource/Limit | Free | Paid | Notes |\n|----------------|------|------|-------|\n| Max asset size | 25 MiB | 25 MiB | Per file |\n| Total assets | 20,000 | **100,000** | Requires Wrangler 4.34.0+ (Sep 2025) |\n| Worker invocations | 100k/day | 10M/month | Optimize with `run_worker_first` patterns |\n| Asset storage | Unlimited | Unlimited | Included |\n\n### Version Requirements\n\n| Feature | Minimum Wrangler Version |\n|---------|--------------------------|\n| 100k file limit (paid) | 4.34.0 |\n| Vite plugin | 4.0.0 + @cloudflare/vite-plugin 1.0.0 |\n| Navigation optimization | 4.0.0 + compatibility_date: \"2025-04-01\" |\n\n## Performance Tips\n\n### 1. Use Hashed Filenames\n\nEnable long-term caching with content-hashed filenames:\n\n```\napp.a3b2c1d4.js\nstyles.e5f6g7h8.css\n```\n\nMost bundlers (Vite, Webpack, Parcel) do this automatically.\n\n### 2. Minimize Worker Invocations\n\nServe assets directly when possible:\n\n```jsonc\n{\n \"assets\": {\n // Only invoke Worker for dynamic routes\n \"run_worker_first\": [\"/api/*\", \"/auth/*\"]\n }\n}\n```\n\n### 3. Leverage Browser Cache\n\nSet appropriate `Cache-Control` headers:\n\n```typescript\n// Versioned assets\n'Cache-Control': 'public, max-age=31536000, immutable'\n\n// HTML (revalidate often)\n'Cache-Control': 'public, max-age=0, must-revalidate'\n```\n\nSee patterns.md:169-189 for implementation.\n\n### 4. Use .assetsignore\n\nReduce upload time by excluding unnecessary files:\n\n```\n*.map\n*.md\n.DS_Store\nnode_modules/\n```\n\nSee configuration.md:107-126 for details.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/static-assets/patterns.md", "content": "### Common Patterns\n\n**1. Forward request to assets:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**2. Fetch specific asset by path:**\n\n```typescript\nconst response = await env.ASSETS.fetch(\"https://assets.local/logo.png\");\n```\n\n**3. Modify request before fetching asset:**\n\n```typescript\nconst url = new URL(request.url);\nurl.pathname = \"/index.html\";\nreturn env.ASSETS.fetch(new Request(url, request));\n```\n\n**4. Transform asset response:**\n\n```typescript\nconst response = await env.ASSETS.fetch(request);\nconst modifiedResponse = new Response(response.body, response);\nmodifiedResponse.headers.set(\"X-Custom-Header\", \"value\");\nmodifiedResponse.headers.set(\"Cache-Control\", \"public, max-age=3600\");\nreturn modifiedResponse;\n```\n\n**5. Conditional asset serving:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname === '/') {\n return env.ASSETS.fetch('/index.html');\n }\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**6. SPA with API routes:**\n\nMost common full-stack pattern - static SPA with backend API:\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname.startsWith('/api/')) {\n return handleAPI(request, env);\n }\n return env.ASSETS.fetch(request);\n }\n};\n\nasync function handleAPI(request: Request, env: Env): Promise {\n return new Response(JSON.stringify({ status: 'ok' }), {\n headers: { 'Content-Type': 'application/json' }\n });\n}\n```\n\n**Config:** Set `run_worker_first: [\"/api/*\"]` (see configuration.md:66-106)\n\n**7. Auth gating for protected assets:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname.startsWith('/admin/')) {\n const session = await validateSession(request, env);\n if (!session) {\n return Response.redirect('/login', 302);\n }\n }\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**Config:** Set `run_worker_first: [\"/admin/*\"]`\n\n**8. Custom headers for security:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const response = await env.ASSETS.fetch(request);\n const secureResponse = new Response(response.body, response);\n secureResponse.headers.set('X-Frame-Options', 'DENY');\n secureResponse.headers.set('X-Content-Type-Options', 'nosniff');\n secureResponse.headers.set('Content-Security-Policy', \"default-src 'self'\");\n return secureResponse;\n }\n};\n```\n\n**9. A/B testing via cookies:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const cookies = request.headers.get('Cookie') || '';\n const variant = cookies.includes('variant=b') ? 'b' : 'a';\n const url = new URL(request.url);\n if (url.pathname === '/') {\n return env.ASSETS.fetch(`/index-${variant}.html`);\n }\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**10. Locale-based routing:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const locale = request.headers.get('Accept-Language')?.split(',')[0] || 'en';\n const url = new URL(request.url);\n if (url.pathname === '/') {\n return env.ASSETS.fetch(`/${locale}/index.html`);\n }\n if (!url.pathname.startsWith(`/${locale}/`)) {\n url.pathname = `/${locale}${url.pathname}`;\n }\n return env.ASSETS.fetch(url);\n }\n};\n```\n\n**11. OAuth callback handling:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const url = new URL(request.url);\n if (url.pathname === '/auth/callback') {\n const code = url.searchParams.get('code');\n if (code) {\n const session = await exchangeCode(code, env);\n return new Response(null, {\n status: 302,\n headers: {\n 'Location': '/',\n 'Set-Cookie': `session=${session}; HttpOnly; Secure; SameSite=Lax`\n }\n });\n }\n }\n return env.ASSETS.fetch(request);\n }\n};\n```\n\n**Config:** Set `run_worker_first: [\"/auth/*\"]`\n\n**12. Cache control override:**\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const response = await env.ASSETS.fetch(request);\n const url = new URL(request.url);\n // Immutable assets (hashed filenames)\n if (/\\.[a-f0-9]{8,}\\.(js|css|png|jpg)$/.test(url.pathname)) {\n return new Response(response.body, {\n ...response,\n headers: {\n ...Object.fromEntries(response.headers),\n 'Cache-Control': 'public, max-age=31536000, immutable'\n }\n });\n }\n return response;\n }\n};\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/README.md", "content": "# Cloudflare Stream\n\nServerless live and on-demand video streaming platform with one API.\n\n## Overview\n\nCloudflare Stream provides video upload, storage, encoding, and delivery without managing infrastructure. Runs on Cloudflare's global network.\n\n### Key Features\n- **On-demand video**: Upload, encode, store, deliver\n- **Live streaming**: RTMPS/SRT ingestion with ABR\n- **Direct creator uploads**: End users upload without API keys\n- **Signed URLs**: Token-based access control\n- **Analytics**: Server-side metrics via GraphQL\n- **Webhooks**: Processing notifications\n- **Captions**: Upload or AI-generate subtitles\n- **Watermarks**: Apply branding to videos\n- **Downloads**: Enable MP4 offline viewing\n\n## Core Concepts\n\n### Video Upload Methods\n1. **API Upload (TUS protocol)**: Direct server upload\n2. **Upload from URL**: Import from external source\n3. **Direct Creator Uploads**: User-generated content (recommended)\n\n### Playback Options\n1. **Stream Player (iframe)**: Built-in, optimized player\n2. **Custom Player (HLS/DASH)**: Video.js, HLS.js integration\n3. **Thumbnails**: Static or animated previews\n\n### Access Control\n- **Public**: No restrictions\n- **requireSignedURLs**: Token-based access\n- **allowedOrigins**: Domain restrictions\n- **Access Rules**: Geo/IP restrictions in tokens\n\n### Live Streaming\n- RTMPS/SRT ingest from OBS, FFmpeg\n- Automatic recording to on-demand\n- Simulcast to YouTube, Twitch, etc.\n- WebRTC support for browser streaming\n\n## Quick Start\n\n**Upload video via API**\n```bash\ncurl -X POST \\\n \"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"url\": \"https://example.com/video.mp4\"}'\n```\n\n**Embed player**\n```html\n.cloudflarestream.com//iframe\"\n style=\"border: none;\"\n height=\"720\" width=\"1280\"\n allow=\"accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;\"\n allowfullscreen=\"true\"\n>\n```\n\n**Create live input**\n```bash\ncurl -X POST \\\n \"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"recording\": {\"mode\": \"automatic\"}}'\n```\n\n## Limits\n\n- Max file size: 30 GB\n- Max frame rate: 60 fps (recommended)\n- Supported formats: MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime\n\n## Pricing\n\n- $5/1000 min stored\n- $1/1000 min delivered\n\n## Resources\n\n- Dashboard: https://dash.cloudflare.com/?to=/:account/stream\n- API Docs: https://developers.cloudflare.com/api/resources/stream/\n- Stream Docs: https://developers.cloudflare.com/stream/\n\n## Reading Order\n\n| Order | File | Purpose | When to Use |\n|-------|------|---------|-------------|\n| 1 | [configuration.md](./configuration.md) | Setup SDKs, env vars, signing keys | Starting new project |\n| 2 | [api.md](./api.md) | On-demand video APIs | Implementing uploads/playback |\n| 3 | [api-live.md](./api-live.md) | Live streaming APIs | Building live streaming |\n| 4 | [patterns.md](./patterns.md) | Full-stack flows, TUS, JWT signing | Implementing workflows |\n| 5 | [gotchas.md](./gotchas.md) | Errors, limits, troubleshooting | Debugging issues |\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - Setup, environment variables, wrangler config\n- [api.md](./api.md) - On-demand video upload, playback, management APIs\n- [api-live.md](./api-live.md) - Live streaming (RTMPS/SRT/WebRTC), simulcast\n- [patterns.md](./patterns.md) - Full-stack flows, state management, best practices\n- [gotchas.md](./gotchas.md) - Error codes, troubleshooting, limits\n\n## See Also\n\n- [workers](../workers/) - Deploy Stream APIs in Workers\n- [pages](../pages/) - Integrate Stream with Pages\n- [workers-ai](../workers-ai/) - AI-generate captions\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/api-live.md", "content": "# Stream Live Streaming API\n\nLive input creation, status checking, simulcast, and WebRTC streaming.\n\n## Create Live Input\n\n### Using Cloudflare SDK\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: env.CF_API_TOKEN });\n\nconst liveInput = await client.stream.liveInputs.create({\n account_id: env.CF_ACCOUNT_ID,\n recording: { mode: 'automatic', timeoutSeconds: 30 },\n deleteRecordingAfterDays: 30\n});\n\n// Returns: { uid, rtmps, srt, webRTC }\n```\n\n### Raw fetch API\n\n```typescript\nasync function createLiveInput(accountId: string, apiToken: string) {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n recording: { mode: 'automatic', timeoutSeconds: 30 },\n deleteRecordingAfterDays: 30\n })\n }\n );\n const { result } = await response.json();\n return {\n uid: result.uid,\n rtmps: { url: result.rtmps.url, streamKey: result.rtmps.streamKey },\n srt: { url: result.srt.url, streamId: result.srt.streamId, passphrase: result.srt.passphrase },\n webRTC: result.webRTC\n };\n}\n```\n\n## Check Live Status\n\n```typescript\nasync function getLiveStatus(accountId: string, liveInputId: string, apiToken: string) {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}`,\n { headers: { 'Authorization': `Bearer ${apiToken}` } }\n );\n const { result } = await response.json();\n return {\n isLive: result.status?.current?.state === 'connected',\n recording: result.recording,\n status: result.status\n };\n}\n```\n\n## Simulcast (Live Outputs)\n\n### Create Output\n\n```typescript\nasync function createLiveOutput(\n accountId: string, liveInputId: string, apiToken: string,\n outputUrl: string, streamKey: string\n) {\n return fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}/outputs`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n url: `${outputUrl}/${streamKey}`,\n enabled: true,\n streamKey // For platforms like YouTube, Twitch\n })\n }\n ).then(r => r.json());\n}\n```\n\n### Example: Simulcast to YouTube + Twitch\n\n```typescript\nconst liveInput = await createLiveInput(accountId, apiToken);\n\n// Add YouTube output\nawait createLiveOutput(\n accountId, liveInput.uid, apiToken,\n 'rtmp://a.rtmp.youtube.com/live2',\n 'your-youtube-stream-key'\n);\n\n// Add Twitch output\nawait createLiveOutput(\n accountId, liveInput.uid, apiToken,\n 'rtmp://live.twitch.tv/app',\n 'your-twitch-stream-key'\n);\n```\n\n## WebRTC Streaming (WHIP/WHEP)\n\n### Browser to Stream (WHIP)\n\n```typescript\nasync function startWebRTCBroadcast(liveInputId: string) {\n const pc = new RTCPeerConnection();\n \n // Add local media tracks\n const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });\n stream.getTracks().forEach(track => pc.addTrack(track, stream));\n \n // Create offer\n const offer = await pc.createOffer();\n await pc.setLocalDescription(offer);\n \n // Send to Stream via WHIP\n const response = await fetch(\n `https://customer-.cloudflarestream.com/${liveInputId}/webRTC/publish`,\n {\n method: 'POST',\n headers: { 'Content-Type': 'application/sdp' },\n body: offer.sdp\n }\n );\n \n const answer = await response.text();\n await pc.setRemoteDescription({ type: 'answer', sdp: answer });\n}\n```\n\n### Stream to Browser (WHEP)\n\n```typescript\nasync function playWebRTCStream(videoId: string) {\n const pc = new RTCPeerConnection();\n \n pc.addTransceiver('video', { direction: 'recvonly' });\n pc.addTransceiver('audio', { direction: 'recvonly' });\n \n const offer = await pc.createOffer();\n await pc.setLocalDescription(offer);\n \n const response = await fetch(\n `https://customer-.cloudflarestream.com/${videoId}/webRTC/play`,\n {\n method: 'POST',\n headers: { 'Content-Type': 'application/sdp' },\n body: offer.sdp\n }\n );\n \n const answer = await response.text();\n await pc.setRemoteDescription({ type: 'answer', sdp: answer });\n \n return pc;\n}\n```\n\n## Recording Settings\n\n| Mode | Behavior |\n|------|----------|\n| `automatic` | Record all live streams |\n| `off` | No recording |\n| `timeoutSeconds` | Stop recording after N seconds of inactivity |\n\n```typescript\nconst recordingConfig = {\n mode: 'automatic',\n timeoutSeconds: 30, // Auto-stop 30s after stream ends\n requireSignedURLs: true, // Require token for VOD playback\n allowedOrigins: ['https://yourdomain.com']\n};\n```\n\n## In This Reference\n\n- [README.md](./README.md) - Overview and quick start\n- [api.md](./api.md) - On-demand video APIs\n- [configuration.md](./configuration.md) - Setup and config\n- [patterns.md](./patterns.md) - Full-stack flows, best practices\n- [gotchas.md](./gotchas.md) - Error codes, troubleshooting\n\n## See Also\n\n- [workers](../workers/) - Deploy live APIs in Workers\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/api.md", "content": "# Stream API Reference\n\nUpload, playback, live streaming, and management APIs.\n\n## Upload APIs\n\n### Direct Creator Upload (Recommended)\n\n**Backend: Create upload URL (SDK)**\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: env.CF_API_TOKEN });\n\nconst uploadData = await client.stream.directUpload.create({\n account_id: env.CF_ACCOUNT_ID,\n maxDurationSeconds: 3600,\n requireSignedURLs: true,\n meta: { creator: 'user-123' }\n});\n// Returns: { uploadURL: string, uid: string }\n```\n\n**Frontend: Upload file**\n```typescript\nasync function uploadVideo(file: File, uploadURL: string) {\n const formData = new FormData();\n formData.append('file', file);\n return fetch(uploadURL, { method: 'POST', body: formData }).then(r => r.json());\n}\n```\n\n### Upload from URL\n\n```typescript\nconst video = await client.stream.copy.create({\n account_id: env.CF_ACCOUNT_ID,\n url: 'https://example.com/video.mp4',\n meta: { name: 'My Video' },\n requireSignedURLs: false\n});\n```\n\n## Playback APIs\n\n### Embed Player (iframe)\n\n```html\n.cloudflarestream.com//iframe?autoplay=true&muted=true\"\n style=\"border: none;\" height=\"720\" width=\"1280\"\n allow=\"accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;\"\n allowfullscreen=\"true\"\n>\n```\n\n### HLS/DASH Manifest URLs\n\n```typescript\n// HLS\nconst hlsUrl = `https://customer-.cloudflarestream.com/${videoId}/manifest/video.m3u8`;\n\n// DASH\nconst dashUrl = `https://customer-.cloudflarestream.com/${videoId}/manifest/video.mpd`;\n```\n\n### Thumbnails\n\n```typescript\n// At specific time (seconds)\nconst thumb = `https://customer-.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=10s`;\n\n// By percentage\nconst thumbPct = `https://customer-.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=50%`;\n\n// Animated GIF\nconst gif = `https://customer-.cloudflarestream.com/${videoId}/thumbnails/thumbnail.gif`;\n```\n\n## Signed URLs\n\n```typescript\n// Low volume (<1k/day): Use API\nasync function getSignedToken(accountId: string, videoId: string, apiToken: string) {\n const response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/token`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n exp: Math.floor(Date.now() / 1000) + 3600,\n accessRules: [{ type: 'ip.geoip.country', action: 'allow', country: ['US'] }]\n })\n }\n );\n return (await response.json()).result.token;\n}\n\n// High volume: Self-sign with RS256 JWT (see \"Self-Sign JWT\" in patterns.md)\n```\n\n## Captions & Clips\n\n### Upload Captions\n\n```typescript\nasync function uploadCaption(\n accountId: string, videoId: string, apiToken: string,\n language: string, captionFile: File\n) {\n const formData = new FormData();\n formData.append('file', captionFile);\n return fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/${language}`,\n {\n method: 'PUT',\n headers: { 'Authorization': `Bearer ${apiToken}` },\n body: formData\n }\n ).then(r => r.json());\n}\n```\n\n### Generate AI Captions\n\n```typescript\n// TODO: Requires Workers AI integration - see workers-ai reference\nasync function generateAICaptions(accountId: string, videoId: string, apiToken: string) {\n return fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/generate`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({ language: 'en' })\n }\n ).then(r => r.json());\n}\n```\n\n### Clip Video\n\n```typescript\nasync function clipVideo(\n accountId: string, videoId: string, apiToken: string,\n startTime: number, endTime: number\n) {\n return fetch(\n `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/clip`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n clippedFromVideoUID: videoId,\n startTimeSeconds: startTime,\n endTimeSeconds: endTime\n })\n }\n ).then(r => r.json());\n}\n```\n\n## Video Management\n\n```typescript\n// List videos\nconst videos = await client.stream.videos.list({\n account_id: env.CF_ACCOUNT_ID,\n search: 'keyword' // optional\n});\n\n// Get video details\nconst video = await client.stream.videos.get(videoId, {\n account_id: env.CF_ACCOUNT_ID\n});\n\n// Update video\nawait client.stream.videos.update(videoId, {\n account_id: env.CF_ACCOUNT_ID,\n meta: { title: 'New Title' },\n requireSignedURLs: true\n});\n\n// Delete video\nawait client.stream.videos.delete(videoId, {\n account_id: env.CF_ACCOUNT_ID\n});\n```\n\n## In This Reference\n\n- [README.md](./README.md) - Overview and quick start\n- [configuration.md](./configuration.md) - Setup and config\n- [api-live.md](./api-live.md) - Live streaming APIs (RTMPS/SRT/WebRTC)\n- [patterns.md](./patterns.md) - Full-stack flows, best practices\n- [gotchas.md](./gotchas.md) - Error codes, troubleshooting\n\n## See Also\n\n- [workers](../workers/) - Deploy Stream APIs in Workers\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/configuration.md", "content": "# Stream Configuration\n\nSetup, environment variables, and wrangler configuration.\n\n## Installation\n\n```bash\n# Official Cloudflare SDK (Node.js, Workers, Pages)\nnpm install cloudflare\n\n# React component library\nnpm install @cloudflare/stream-react\n\n# TUS resumable uploads (large files)\nnpm install tus-js-client\n```\n\n## Environment Variables\n\n```bash\n# Required\nCF_ACCOUNT_ID=your-account-id\nCF_API_TOKEN=your-api-token\n\n# For signed URLs (high volume)\nSTREAM_KEY_ID=your-key-id\nSTREAM_JWK=base64-encoded-jwk\n\n# For webhooks\nWEBHOOK_SECRET=your-webhook-secret\n\n# Customer subdomain (from dashboard)\nSTREAM_CUSTOMER_CODE=your-customer-code\n```\n\n## Wrangler Configuration\n\n```jsonc\n{\n \"name\": \"stream-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \"vars\": {\n \"CF_ACCOUNT_ID\": \"your-account-id\"\n }\n // Store secrets: wrangler secret put CF_API_TOKEN\n // wrangler secret put STREAM_KEY_ID\n // wrangler secret put STREAM_JWK\n // wrangler secret put WEBHOOK_SECRET\n}\n```\n\n## Signing Keys (High Volume)\n\nCreate once for self-signing tokens (thousands of daily users).\n\n**Create key**\n```bash\ncurl -X POST \\\n \"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys\" \\\n -H \"Authorization: Bearer \"\n\n# Save `id` and `jwk` (base64) from response\n```\n\n**Store in secrets**\n```bash\nwrangler secret put STREAM_KEY_ID\nwrangler secret put STREAM_JWK\n```\n\n## Webhooks\n\n**Setup webhook URL**\n```bash\ncurl -X PUT \\\n \"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/webhook\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"notificationUrl\": \"https://your-worker.workers.dev/webhook\"}'\n\n# Save the returned `secret` for signature verification\n```\n\n**Store secret**\n```bash\nwrangler secret put WEBHOOK_SECRET\n```\n\n## Direct Upload / Live / Watermark Config\n\n```typescript\n// Direct upload\nconst uploadConfig = {\n maxDurationSeconds: 3600,\n expiry: new Date(Date.now() + 3600000).toISOString(),\n requireSignedURLs: true,\n allowedOrigins: ['https://yourdomain.com'],\n meta: { creator: 'user-123' }\n};\n\n// Live input\nconst liveConfig = {\n recording: { mode: 'automatic', timeoutSeconds: 30 },\n deleteRecordingAfterDays: 30\n};\n\n// Watermark\nconst watermark = {\n name: 'Logo', opacity: 0.7, padding: 20,\n position: 'lowerRight', scale: 0.15\n};\n```\n\n## Access Rules & Player Config\n\n```typescript\n// Access rules: allow US/CA, block CN/RU, or IP allowlist\nconst geoRestrict = [\n { type: 'ip.geoip.country', action: 'allow', country: ['US', 'CA'] },\n { type: 'any', action: 'block' }\n];\n\n// Player params for iframe\nconst playerParams = new URLSearchParams({\n autoplay: 'true', muted: 'true', preload: 'auto', defaultTextTrack: 'en'\n});\n```\n\n## In This Reference\n\n- [README.md](./README.md) - Overview and quick start\n- [api.md](./api.md) - On-demand video APIs\n- [api-live.md](./api-live.md) - Live streaming APIs\n- [patterns.md](./patterns.md) - Full-stack flows, best practices\n- [gotchas.md](./gotchas.md) - Error codes, troubleshooting\n\n## See Also\n\n- [wrangler](../wrangler/) - Wrangler CLI and configuration\n- [workers](../workers/) - Deploy Stream APIs in Workers\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/gotchas.md", "content": "# Stream Gotchas\n\n## Common Errors\n\n### \"ERR_NON_VIDEO\"\n\n**Cause:** Uploaded file is not a valid video format\n**Solution:** Ensure file is in supported format (MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime)\n\n### \"ERR_DURATION_EXCEED_CONSTRAINT\"\n\n**Cause:** Video duration exceeds `maxDurationSeconds` constraint\n**Solution:** Increase `maxDurationSeconds` in direct upload config or trim video before upload\n\n### \"ERR_FETCH_ORIGIN_ERROR\"\n\n**Cause:** Failed to download video from URL (upload from URL)\n**Solution:** Ensure URL is publicly accessible, uses HTTPS, and video file is available\n\n### \"ERR_MALFORMED_VIDEO\"\n\n**Cause:** Video file is corrupted or improperly encoded\n**Solution:** Re-encode video using FFmpeg or check source file integrity\n\n### \"ERR_DURATION_TOO_SHORT\"\n\n**Cause:** Video must be at least 0.1 seconds long\n**Solution:** Ensure video has valid duration (not a single frame)\n\n## Troubleshooting\n\n### Video stuck in \"inprogress\" state\n- **Cause**: Processing large/complex video\n- **Solution**: Wait up to 5 minutes for processing; use webhooks instead of polling\n\n### Signed URL returns 403\n- **Cause**: Token expired or invalid signature\n- **Solution**: Check expiration timestamp, verify JWK is correct, ensure clock sync\n\n### Live stream not connecting\n- **Cause**: Invalid RTMPS URL or stream key\n- **Solution**: Use exact URL/key from API, ensure firewall allows outbound 443\n\n### Webhook signature verification fails\n- **Cause**: Incorrect secret or timestamp window\n- **Solution**: Use exact secret from webhook setup, allow 5-minute timestamp drift\n\n### Video uploads but isn't visible\n- **Cause**: `requireSignedURLs` enabled without providing token\n- **Solution**: Generate signed token or set `requireSignedURLs: false` for public videos\n\n### Player shows infinite loading\n- **Cause**: CORS issue with allowedOrigins\n- **Solution**: Add your domain to `allowedOrigins` array\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Max file size | 30 GB |\n| Max frame rate | 60 fps (recommended) |\n| Max duration per direct upload | Configurable via `maxDurationSeconds` |\n| Token generation (API endpoint) | 1,000/day recommended (use signing keys for higher) |\n| Live input outputs (simulcast) | 5 per live input |\n| Webhook retry attempts | 5 (exponential backoff) |\n| Webhook timeout | 30 seconds |\n| Caption file size | 5 MB |\n| Watermark image size | 2 MB |\n| Metadata keys per video | Unlimited |\n| Search results per page | Max 1,000 |\n\n## Performance Issues\n\n### Upload is slow\n- **Cause**: Large file size or network constraints\n- **Solution**: Use TUS resumable upload, compress video before upload, check bandwidth\n\n### Playback buffering\n- **Cause**: Network congestion or low bandwidth\n- **Solution**: Use ABR (adaptive bitrate) with HLS/DASH, reduce max bitrate\n\n### High processing time\n- **Cause**: Complex video codec, high resolution\n- **Solution**: Pre-encode with H.264 (most efficient), reduce resolution\n\n## Type Safety\n\n```typescript\n// Error response type\ninterface StreamError {\n success: false;\n errors: Array<{\n code: number;\n message: string;\n }>;\n}\n\n// Handle errors\nasync function uploadWithErrorHandling(url: string, file: File) {\n const formData = new FormData();\n formData.append('file', file);\n const response = await fetch(url, { method: 'POST', body: formData });\n const result = await response.json();\n \n if (!result.success) {\n throw new Error(result.errors[0]?.message || 'Upload failed');\n }\n return result;\n}\n```\n\n## Security Gotchas\n\n1. **Never expose API token in frontend** - Use direct creator uploads\n2. **Always verify webhook signatures** - Prevent spoofed notifications\n3. **Set appropriate token expiration** - Short-lived for security\n4. **Use requireSignedURLs for private content** - Prevent unauthorized access\n5. **Whitelist allowedOrigins** - Prevent hotlinking/embedding on unauthorized sites\n\n## In This Reference\n\n- [README.md](./README.md) - Overview and quick start\n- [configuration.md](./configuration.md) - Setup and config\n- [api.md](./api.md) - On-demand video APIs\n- [api-live.md](./api-live.md) - Live streaming APIs\n- [patterns.md](./patterns.md) - Full-stack flows, best practices\n\n## See Also\n\n- [workers](../workers/) - Deploy Stream APIs securely\n" }, { "path": "skills/.curated/cloudflare-deploy/references/stream/patterns.md", "content": "# Stream Patterns\n\nCommon workflows, full-stack flows, and best practices.\n\n## React Stream Player\n\n`npm install @cloudflare/stream-react`\n\n```tsx\nimport { Stream } from '@cloudflare/stream-react';\n\nexport function VideoPlayer({ videoId, token }: { videoId: string; token?: string }) {\n return ;\n}\n```\n\n## Full-Stack Upload Flow\n\n**Backend API (Workers/Pages)**\n```typescript\nimport Cloudflare from 'cloudflare';\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const { videoName } = await request.json();\n const client = new Cloudflare({ apiToken: env.CF_API_TOKEN });\n const { uploadURL, uid } = await client.stream.directUpload.create({\n account_id: env.CF_ACCOUNT_ID,\n maxDurationSeconds: 3600,\n requireSignedURLs: true,\n meta: { name: videoName }\n });\n return Response.json({ uploadURL, uid });\n }\n};\n```\n\n**Frontend component**\n```tsx\nimport { useState } from 'react';\n\nexport function VideoUploader() {\n const [uploading, setUploading] = useState(false);\n const [progress, setProgress] = useState(0);\n \n async function handleUpload(file: File) {\n setUploading(true);\n const { uploadURL, uid } = await fetch('/api/upload-url', {\n method: 'POST',\n body: JSON.stringify({ videoName: file.name })\n }).then(r => r.json());\n \n const xhr = new XMLHttpRequest();\n xhr.upload.onprogress = (e) => setProgress((e.loaded / e.total) * 100);\n xhr.onload = () => { setUploading(false); window.location.href = `/videos/${uid}`; };\n xhr.open('POST', uploadURL);\n const formData = new FormData();\n formData.append('file', file);\n xhr.send(formData);\n }\n \n return (\n
\n e.target.files?.[0] && handleUpload(e.target.files[0])} disabled={uploading} />\n {uploading && }\n
\n );\n}\n```\n\n## TUS Resumable Upload\n\nFor large files (>500MB). `npm install tus-js-client`\n\n```typescript\nimport * as tus from 'tus-js-client';\n\nasync function uploadWithTUS(file: File, uploadURL: string, onProgress?: (pct: number) => void) {\n return new Promise((resolve, reject) => {\n const upload = new tus.Upload(file, {\n endpoint: uploadURL,\n retryDelays: [0, 3000, 5000, 10000, 20000],\n chunkSize: 50 * 1024 * 1024,\n metadata: { filename: file.name, filetype: file.type },\n onError: reject,\n onProgress: (up, total) => onProgress?.((up / total) * 100),\n onSuccess: () => resolve(upload.url?.split('/').pop() || '')\n });\n upload.start();\n });\n}\n```\n\n## Video State Polling\n\n```typescript\nasync function waitForVideoReady(client: Cloudflare, accountId: string, videoId: string) {\n for (let i = 0; i < 60; i++) {\n const video = await client.stream.videos.get(videoId, { account_id: accountId });\n if (video.readyToStream || video.status.state === 'error') return video;\n await new Promise(resolve => setTimeout(resolve, 5000));\n }\n throw new Error('Video processing timeout');\n}\n```\n\n## Webhook Handler\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const signature = request.headers.get('Webhook-Signature');\n const body = await request.text();\n if (!signature || !await verifyWebhook(signature, body, env.WEBHOOK_SECRET)) {\n return new Response('Unauthorized', { status: 401 });\n }\n const payload = JSON.parse(body);\n if (payload.readyToStream) console.log(`Video ${payload.uid} ready`);\n return new Response('OK');\n }\n};\n\nasync function verifyWebhook(sig: string, body: string, secret: string): Promise {\n const parts = Object.fromEntries(sig.split(',').map(p => p.split('=')));\n const timestamp = parseInt(parts.time || '0', 10);\n if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;\n \n const key = await crypto.subtle.importKey(\n 'raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']\n );\n const computed = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${timestamp}.${body}`));\n const hex = Array.from(new Uint8Array(computed), b => b.toString(16).padStart(2, '0')).join('');\n return hex === parts.sig1;\n}\n```\n\n## Self-Sign JWT (High Volume Tokens)\n\nFor >1k tokens/day. Prerequisites: Create signing key (see configuration.md).\n\n```typescript\nasync function selfSignToken(keyId: string, jwkBase64: string, videoId: string, expiresIn = 3600) {\n const key = await crypto.subtle.importKey(\n 'jwk', JSON.parse(atob(jwkBase64)), { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']\n );\n const now = Math.floor(Date.now() / 1000);\n const header = btoa(JSON.stringify({ alg: 'RS256', kid: keyId })).replace(/=/g, '').replace(/\\+/g, '-').replace(/\\//g, '_');\n const payload = btoa(JSON.stringify({ sub: videoId, kid: keyId, exp: now + expiresIn, nbf: now }))\n .replace(/=/g, '').replace(/\\+/g, '-').replace(/\\//g, '_');\n const message = `${header}.${payload}`;\n const sig = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, new TextEncoder().encode(message));\n const b64Sig = btoa(String.fromCharCode(...new Uint8Array(sig))).replace(/=/g, '').replace(/\\+/g, '-').replace(/\\//g, '_');\n return `${message}.${b64Sig}`;\n}\n\n// With access rules (geo-restriction)\nconst payloadWithRules = {\n sub: videoId, kid: keyId, exp: now + 3600, nbf: now,\n accessRules: [{ type: 'ip.geoip.country', action: 'allow', country: ['US'] }]\n};\n```\n\n## Best Practices\n\n- **Use Direct Creator Uploads** - Avoid proxying through servers\n- **Enable requireSignedURLs** - Control private content access\n- **Self-sign tokens at scale** - Use signing keys for >1k/day\n- **Set allowedOrigins** - Prevent hotlinking\n- **Use webhooks over polling** - Efficient status updates\n- **Set maxDurationSeconds** - Prevent abuse\n- **Enable live recordings** - Auto VOD after stream\n\n## In This Reference\n\n- [README.md](./README.md) - Overview and quick start\n- [configuration.md](./configuration.md) - Setup and config\n- [api.md](./api.md) - On-demand video APIs\n- [api-live.md](./api-live.md) - Live streaming APIs\n- [gotchas.md](./gotchas.md) - Error codes, troubleshooting\n\n## See Also\n\n- [workers](../workers/) - Deploy Stream APIs in Workers\n- [pages](../pages/) - Integrate Stream with Pages\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tail-workers/README.md", "content": "# Cloudflare Tail Workers\n\nSpecialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.\n\n## When to Use This Reference\n\n- Implementing observability/logging for Cloudflare Workers\n- Processing Worker execution events, logs, exceptions\n- Building custom analytics or error tracking\n- Configuring real-time event streaming\n- Working with tail handlers or tail consumers\n\n## Core Concepts\n\n### What Are Tail Workers?\n\nTail Workers automatically process events from producer Workers (the Workers being monitored). They receive:\n- HTTP request/response info\n- Console logs (`console.log/error/warn/debug`)\n- Uncaught exceptions\n- Execution outcomes (`ok`, `exception`, `exceededCpu`, etc.)\n- Diagnostic channel events\n\n**Key characteristics:**\n- Invoked AFTER producer finishes executing\n- Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests\n- Billed by CPU time, not request count\n- Available on Workers Paid and Enterprise tiers\n\n### Alternative: OpenTelemetry Export\n\n**Before using Tail Workers, consider OpenTelemetry:**\n\nFor batch exports to observability tools (Sentry, Grafana, Honeycomb):\n- OTEL export sends logs/traces in batches (more efficient)\n- Built-in integrations with popular platforms\n- Lower overhead than Tail Workers\n- **Use Tail Workers only for custom real-time processing**\n\n## Decision Tree\n\n```\nNeed observability for Workers?\n├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?\n│ └─ Use OpenTelemetry export (not Tail Workers)\n├─ Custom real-time processing needed?\n│ ├─ Aggregated metrics?\n│ │ └─ Use Tail Worker + Analytics Engine\n│ ├─ Error tracking?\n│ │ └─ Use Tail Worker + external service\n│ ├─ Custom logging/debugging?\n│ │ └─ Use Tail Worker + KV/HTTP endpoint\n│ └─ Complex event processing?\n│ └─ Use Tail Worker + Durable Objects\n└─ Quick debugging?\n └─ Use `wrangler tail` (different from Tail Workers)\n```\n\n## Reading Order\n\n1. **[configuration.md](configuration.md)** - Set up Tail Workers\n2. **[api.md](api.md)** - Handler signature, types, redaction\n3. **[patterns.md](patterns.md)** - Common use cases and integrations\n4. **[gotchas.md](gotchas.md)** - Pitfalls and debugging tips\n\n## Quick Example\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n // Process events from producer Worker\n ctx.waitUntil(\n fetch(env.LOG_ENDPOINT, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(events),\n })\n );\n }\n};\n```\n\n## Related Skills\n\n- **observability** - General Workers observability patterns, OTEL export\n- **analytics-engine** - Aggregated metrics storage for tail event data\n- **durable-objects** - Stateful event processing, batching tail events\n- **logpush** - Alternative for batch log export (non-real-time)\n- **workers-for-platforms** - Dynamic dispatch with tail consumers\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tail-workers/api.md", "content": "# Tail Workers API Reference\n\n## Handler Signature\n\n```typescript\nexport default {\n async tail(\n events: TraceItem[],\n env: Env,\n ctx: ExecutionContext\n ): Promise {\n // Process events\n }\n} satisfies ExportedHandler;\n```\n\n**Parameters:**\n- `events`: Array of `TraceItem` objects (one per producer invocation)\n- `env`: Bindings (KV, D1, R2, env vars, etc.)\n- `ctx`: Context with `waitUntil()` for async work\n\n**CRITICAL:** Tail handlers don't return values. Use `ctx.waitUntil()` for async operations.\n\n## TraceItem Type\n\n```typescript\ninterface TraceItem {\n scriptName: string; // Producer Worker name\n eventTimestamp: number; // Epoch milliseconds\n outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' \n | 'canceled' | 'scriptNotFound' | 'responseStreamDisconnected' | 'unknown';\n \n event?: {\n request?: {\n url: string; // Redacted by default\n method: string;\n headers: Record; // Sensitive headers redacted\n cf?: IncomingRequestCfProperties;\n getUnredacted(): TraceRequest; // Bypass redaction (use carefully)\n };\n response?: {\n status: number;\n };\n };\n \n logs: Array<{\n timestamp: number; // Epoch milliseconds\n level: 'debug' | 'info' | 'log' | 'warn' | 'error';\n message: unknown[]; // Args passed to console function\n }>;\n \n exceptions: Array<{\n timestamp: number; // Epoch milliseconds\n name: string; // Error type (Error, TypeError, etc.)\n message: string; // Error description\n }>;\n \n diagnosticsChannelEvents: Array<{\n channel: string;\n message: unknown;\n timestamp: number; // Epoch milliseconds\n }>;\n}\n```\n\n**Note:** Official SDK uses `TraceItem`, not `TailItem`. Use `@cloudflare/workers-types` for accurate types.\n\n## Timestamp Handling\n\nAll timestamps are **epoch milliseconds**, not seconds:\n\n```typescript\n// ✅ CORRECT - use directly with Date\nconst date = new Date(event.eventTimestamp);\n\n// ❌ WRONG - don't multiply by 1000\nconst date = new Date(event.eventTimestamp * 1000);\n```\n\n## Automatic Redaction\n\nBy default, sensitive data is redacted from `TraceRequest`:\n\n### Header Redaction\n\nHeaders containing these substrings (case-insensitive):\n- `auth`, `key`, `secret`, `token`, `jwt`\n- `cookie`, `set-cookie`\n\nRedacted values show as `\"REDACTED\"`.\n\n### URL Redaction\n\n- **Hex IDs:** 32+ hex digits → `\"REDACTED\"`\n- **Base-64 IDs:** 21+ chars with 2+ upper, 2+ lower, 2+ digits → `\"REDACTED\"`\n\n## Bypassing Redaction\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n for (const event of events) {\n // ⚠️ Use with extreme caution\n const unredacted = event.event?.request?.getUnredacted();\n // unredacted.url and unredacted.headers contain raw values\n }\n }\n};\n```\n\n**Best practices:**\n- Only call `getUnredacted()` when absolutely necessary\n- Never log unredacted sensitive data\n- Implement additional filtering before external transmission\n- Use environment variables for API keys, never hardcode\n\n## Type-Safe Handler\n\n```typescript\ninterface Env {\n LOGS_KV: KVNamespace;\n ANALYTICS: AnalyticsEngineDataset;\n LOG_ENDPOINT: string;\n API_TOKEN: string;\n}\n\nexport default {\n async tail(\n events: TraceItem[],\n env: Env,\n ctx: ExecutionContext\n ): Promise {\n const payload = events.map(event => ({\n script: event.scriptName,\n timestamp: event.eventTimestamp,\n outcome: event.outcome,\n url: event.event?.request?.url,\n status: event.event?.response?.status,\n }));\n \n ctx.waitUntil(\n fetch(env.LOG_ENDPOINT, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(payload),\n })\n );\n }\n} satisfies ExportedHandler;\n```\n\n## Outcome vs HTTP Status\n\n**IMPORTANT:** `outcome` is script execution status, NOT HTTP status.\n\n- Worker returns 500 → `outcome='ok'` if script completed successfully\n- Uncaught exception → `outcome='exception'` regardless of HTTP status\n- CPU limit exceeded → `outcome='exceededCpu'`\n\n```typescript\n// ✅ Check outcome for script execution status\nif (event.outcome === 'exception') {\n // Script threw uncaught exception\n}\n\n// ✅ Check HTTP status separately\nif (event.event?.response?.status === 500) {\n // HTTP 500 returned (script may have handled error)\n}\n```\n\n## Serialization Considerations\n\n`log.message` is `unknown[]` and may contain non-serializable objects:\n\n```typescript\n// ❌ May fail with circular references or BigInt\nJSON.stringify(events);\n\n// ✅ Safe serialization\nconst safePayload = events.map(event => ({\n ...event,\n logs: event.logs.map(log => ({\n ...log,\n message: log.message.map(m => {\n try {\n return JSON.parse(JSON.stringify(m));\n } catch {\n return String(m);\n }\n })\n }))\n}));\n```\n\n**Common serialization issues:**\n- Circular references in logged objects\n- `BigInt` values (not JSON-serializable)\n- Functions or symbols in console.log arguments\n- Large objects exceeding body size limits\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tail-workers/configuration.md", "content": "# Tail Workers Configuration\n\n## Setup Steps\n\n### 1. Create Tail Worker\n\nCreate a Worker with a `tail()` handler:\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n // Process events from producer Worker\n ctx.waitUntil(\n fetch(env.LOG_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(events),\n })\n );\n }\n};\n```\n\n### 2. Configure Producer Worker\n\nIn producer's `wrangler.jsonc`:\n\n```jsonc\n{\n \"name\": \"my-producer-worker\",\n \"tail_consumers\": [\n {\n \"service\": \"my-tail-worker\"\n }\n ]\n}\n```\n\n### 3. Deploy Both Workers\n\n```bash\n# Deploy Tail Worker first\ncd tail-worker\nwrangler deploy\n\n# Then deploy producer Worker\ncd ../producer-worker\nwrangler deploy\n```\n\n## Wrangler Configuration\n\n### Single Tail Consumer\n\n```jsonc\n{\n \"name\": \"producer-worker\",\n \"tail_consumers\": [\n {\n \"service\": \"logging-tail-worker\"\n }\n ]\n}\n```\n\n### Multiple Tail Consumers\n\n```jsonc\n{\n \"name\": \"producer-worker\",\n \"tail_consumers\": [\n {\n \"service\": \"logging-tail-worker\"\n },\n {\n \"service\": \"metrics-tail-worker\"\n }\n ]\n}\n```\n\n**Note:** Each consumer receives ALL events independently.\n\n### Remove Tail Consumer\n\n```jsonc\n{\n \"tail_consumers\": []\n}\n```\n\nThen redeploy producer Worker.\n\n## Environment Variables\n\nTail Workers use same binding syntax as regular Workers:\n\n```jsonc\n{\n \"name\": \"my-tail-worker\",\n \"vars\": {\n \"LOG_ENDPOINT\": \"https://logs.example.com/ingest\"\n },\n \"kv_namespaces\": [\n {\n \"binding\": \"LOGS_KV\",\n \"id\": \"abc123...\"\n }\n ]\n}\n```\n\n## Testing & Development\n\n### Local Testing\n\n**Tail Workers cannot be fully tested with `wrangler dev`.** Deploy to staging environment for testing.\n\n### Testing Strategy\n\n1. Deploy producer Worker to staging\n2. Deploy Tail Worker to staging\n3. Configure `tail_consumers` in producer\n4. Trigger producer Worker requests\n5. Verify Tail Worker receives events (check destination logs/storage)\n\n### Wrangler Tail Command\n\n```bash\n# Stream logs to terminal (NOT Tail Workers)\nwrangler tail my-producer-worker\n```\n\n**This is different from Tail Workers:**\n- `wrangler tail` streams logs to your terminal\n- Tail Workers are Workers that process events programmatically\n\n## Deployment Checklist\n\n- [ ] Tail Worker has `tail()` handler\n- [ ] Tail Worker deployed before producer\n- [ ] Producer's `wrangler.jsonc` has correct `tail_consumers`\n- [ ] Environment variables configured\n- [ ] Tested with staging environment\n- [ ] Monitoring configured for Tail Worker itself\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Max tail consumers per producer | 10 | Each receives all events independently |\n| Events batch size | Up to 100 events per invocation | Larger batches split across invocations |\n| Tail Worker CPU time | Same as regular Workers | 10ms (free), 30ms (paid), 50ms (paid bundle) |\n| Pricing tier | Workers Paid or Enterprise | Not available on free plan |\n| Request body size | 100 MB max | When sending to external endpoints |\n| Event retention | None | Events not retried if tail handler fails |\n\n## Workers for Platforms\n\nFor dynamic dispatch Workers, both dispatch and user Worker events sent to tail consumer:\n\n```jsonc\n{\n \"name\": \"dispatch-worker\",\n \"tail_consumers\": [\n {\n \"service\": \"platform-tail-worker\"\n }\n ]\n}\n```\n\nTail Worker receives TWO `TraceItem` elements per request:\n1. Dynamic dispatch Worker event\n2. User Worker event\n\nSee [patterns.md](patterns.md) for handling.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tail-workers/gotchas.md", "content": "# Tail Workers Gotchas & Debugging\n\n## Critical Pitfalls\n\n### 1. Not Using `ctx.waitUntil()`\n\n**Problem:** Async work doesn't complete or tail Worker times out \n**Cause:** Handlers exit immediately; awaiting blocks processing \n**Solution:**\n\n```typescript\n// ❌ WRONG - fire and forget\nexport default {\n async tail(events) {\n fetch(endpoint, { body: JSON.stringify(events) });\n }\n};\n\n// ❌ WRONG - blocking await\nexport default {\n async tail(events, env, ctx) {\n await fetch(endpoint, { body: JSON.stringify(events) });\n }\n};\n\n// ✅ CORRECT\nexport default {\n async tail(events, env, ctx) {\n ctx.waitUntil(\n (async () => {\n await fetch(endpoint, { body: JSON.stringify(events) });\n await processMore();\n })()\n );\n }\n};\n```\n\n### 2. Missing `tail()` Handler\n\n**Problem:** Producer deployment fails \n**Cause:** Worker in `tail_consumers` doesn't export `tail()` handler \n**Solution:** Ensure `export default { async tail(events, env, ctx) { ... } }`\n\n### 3. Outcome vs HTTP Status\n\n**Problem:** Filtering by wrong status \n**Cause:** `outcome` is script execution status, not HTTP status\n\n```typescript\n// ❌ WRONG\nif (event.outcome === 500) { /* never matches */ }\n\n// ✅ CORRECT\nif (event.outcome === 'exception') { /* script threw */ }\nif (event.event?.response?.status === 500) { /* HTTP 500 */ }\n```\n\n### 4. Timestamp Units\n\n**Problem:** Dates off by 1000x \n**Cause:** Timestamps are epoch milliseconds, not seconds\n\n```typescript\n// ❌ WRONG: const date = new Date(event.eventTimestamp * 1000);\n// ✅ CORRECT: const date = new Date(event.eventTimestamp);\n```\n\n### 5. Type Name Mismatch\n\n**Problem:** Using `TailItem` type \n**Cause:** Old docs used `TailItem`, SDK uses `TraceItem`\n\n```typescript\nimport type { TraceItem } from '@cloudflare/workers-types';\nexport default {\n async tail(events: TraceItem[], env, ctx) { /* ... */ }\n};\n```\n\n### 6. Excessive Logging Volume\n\n**Problem:** Unexpected high costs \n**Cause:** Invoked on EVERY producer request \n**Solution:** Sample events\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n if (Math.random() > 0.1) return; // 10% sample\n ctx.waitUntil(sendToEndpoint(events));\n }\n};\n```\n\n### 7. Serialization Issues\n\n**Problem:** `JSON.stringify()` fails \n**Cause:** `log.message` is `unknown[]` with non-serializable values \n**Solution:**\n\n```typescript\nconst safePayload = events.map(e => ({\n ...e,\n logs: e.logs.map(log => ({\n ...log,\n message: log.message.map(m => {\n try { return JSON.parse(JSON.stringify(m)); }\n catch { return String(m); }\n })\n }))\n}));\n```\n\n### 8. Missing Error Handling\n\n**Problem:** Tail Worker silently fails \n**Cause:** No try/catch \n**Solution:**\n\n```typescript\nctx.waitUntil((async () => {\n try {\n await fetch(env.ENDPOINT, { body: JSON.stringify(events) });\n } catch (error) {\n console.error(\"Tail error:\", error);\n await env.FALLBACK_KV.put(`failed:${Date.now()}`, JSON.stringify(events));\n }\n})());\n```\n\n### 9. Deployment Order\n\n**Problem:** Producer deployment fails \n**Cause:** Tail consumer not deployed yet \n**Solution:** Deploy tail consumer FIRST\n\n```bash\ncd tail-worker && wrangler deploy\ncd ../producer && wrangler deploy\n```\n\n### 10. No Event Retry\n\n**Problem:** Events lost when handler fails \n**Cause:** Failed invocations NOT retried \n**Solution:** Implement fallback storage (see #8)\n\n## Debugging\n\n**View logs:** `wrangler tail my-tail-worker`\n\n**Incremental testing:**\n1. Verify receipt: `console.log('Events:', events.length)`\n2. Inspect structure: `console.log(JSON.stringify(events[0], null, 2))`\n3. Add external call with `ctx.waitUntil()`\n\n**Monitor dashboard:** Check invocation count (matches producer?), error rate, CPU time\n\n## Testing\n\nAdd test endpoint to producer:\n\n```typescript\nexport default {\n async fetch(request) {\n if (request.url.includes('/test')) {\n console.log('Test log');\n throw new Error('Test error');\n }\n return new Response('OK');\n }\n};\n```\n\nTrigger: `curl https://producer.example.workers.dev/test`\n\n## Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| \"Tail consumer not found\" | Not deployed | Deploy tail Worker first |\n| \"No tail handler\" | Missing `tail()` | Add to default export |\n| \"waitUntil is not a function\" | Missing `ctx` | Add `ctx` parameter |\n| Timeout | Blocking await | Use `ctx.waitUntil()` |\n\n## Performance Notes\n\n- Max 100 events per invocation\n- Each consumer receives all events independently\n- CPU limits same as regular Workers\n- For high volume, use Durable Objects batching\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tail-workers/patterns.md", "content": "# Tail Workers Common Patterns\n\n## Community Libraries\n\nWhile most tail Worker implementations are custom, these libraries may help:\n\n**Logging/Observability:**\n- **Axiom** - `axiom-cloudflare-workers` (npm) - Direct Axiom integration\n- **Baselime** - SDK for Baselime observability platform\n- **LogFlare** - Structured log aggregation\n\n**Type Definitions:**\n- **@cloudflare/workers-types** - Official TypeScript types (use `TraceItem`)\n\n**Note:** Most integrations require custom tail handler implementation. See integration examples below.\n\n## Basic Patterns\n\n### HTTP Endpoint Logging\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n const payload = events.map(event => ({\n script: event.scriptName,\n timestamp: event.eventTimestamp,\n outcome: event.outcome,\n url: event.event?.request?.url,\n status: event.event?.response?.status,\n logs: event.logs,\n exceptions: event.exceptions,\n }));\n \n ctx.waitUntil(\n fetch(env.LOG_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(payload),\n })\n );\n }\n};\n```\n\n### Error Tracking Only\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n const errors = events.filter(e => \n e.outcome === 'exception' || e.exceptions.length > 0\n );\n \n if (errors.length === 0) return;\n \n ctx.waitUntil(\n fetch(env.ERROR_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(errors),\n })\n );\n }\n};\n```\n\n## Storage Integration\n\n### KV Storage with TTL\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n ctx.waitUntil(\n Promise.all(events.map(event =>\n env.LOGS_KV.put(\n `log:${event.scriptName}:${event.eventTimestamp}`,\n JSON.stringify(event),\n { expirationTtl: 86400 } // 24 hours\n )\n ))\n );\n }\n};\n```\n\n### Analytics Engine Metrics\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n ctx.waitUntil(\n Promise.all(events.map(event =>\n env.ANALYTICS.writeDataPoint({\n blobs: [event.scriptName, event.outcome],\n doubles: [1, event.event?.response?.status ?? 0],\n indexes: [event.event?.request?.cf?.colo ?? 'unknown'],\n })\n ))\n );\n }\n};\n```\n\n## Filtering & Routing\n\nFilter by route, outcome, or other criteria:\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n // Route filtering\n const apiEvents = events.filter(e => \n e.event?.request?.url?.includes('/api/')\n );\n \n // Multi-destination routing\n const errors = events.filter(e => e.outcome === 'exception');\n const success = events.filter(e => e.outcome === 'ok');\n \n const tasks = [];\n if (errors.length > 0) {\n tasks.push(fetch(env.ERROR_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(errors),\n }));\n }\n if (success.length > 0) {\n tasks.push(fetch(env.SUCCESS_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(success),\n }));\n }\n \n ctx.waitUntil(Promise.all(tasks));\n }\n};\n```\n\n## Sampling\n\nReduce costs by processing only a percentage of events:\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n if (Math.random() > 0.1) return; // 10% sample rate\n ctx.waitUntil(fetch(env.LOG_ENDPOINT, {\n method: \"POST\",\n body: JSON.stringify(events),\n }));\n }\n};\n```\n\n## Advanced Patterns\n\n### Batching with Durable Objects\n\nAccumulate events before sending:\n\n```typescript\nexport default {\n async tail(events, env, ctx) {\n const batch = env.BATCH_DO.get(env.BATCH_DO.idFromName(\"batch\"));\n ctx.waitUntil(batch.fetch(\"https://batch/add\", {\n method: \"POST\",\n body: JSON.stringify(events),\n }));\n }\n};\n```\n\nSee durable-objects skill for full implementation.\n\n### Workers for Platforms\n\nDynamic dispatch sends TWO events per request. Filter by `scriptName` to distinguish dispatch vs user Worker events.\n\n### Error Handling\n\nAlways wrap external calls. See gotchas.md for fallback storage pattern.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/terraform/README.md", "content": "# Cloudflare Terraform Provider\n\n**Expert guidance for Cloudflare Terraform Provider - infrastructure as code for Cloudflare resources.**\n\n## Core Principles\n\n- **Provider-first**: Use Terraform provider for ALL infrastructure - never mix with wrangler.jsonc for the same resources\n- **State management**: Always use remote state (S3, Terraform Cloud, etc.) for team environments\n- **Modular architecture**: Create reusable modules for common patterns (zones, workers, pages)\n- **Version pinning**: Always pin provider version with `~>` for predictable upgrades\n- **Secret management**: Use variables + environment vars for sensitive data - never hardcode API tokens\n\n## Provider Version\n\n| Version | Status | Notes |\n|---------|--------|-------|\n| 5.x | Current | Auto-generated from OpenAPI, breaking changes from v4 |\n| 4.x | Legacy | Manual maintenance, deprecated |\n\n**Critical:** v5 renamed many resources (`cloudflare_record` → `cloudflare_dns_record`, `cloudflare_worker_*` → `cloudflare_workers_*`). See [gotchas.md](./gotchas.md#v5-breaking-changes) for migration details.\n\n## Provider Setup\n\n### Basic Configuration\n\n```hcl\nterraform {\n required_version = \">= 1.0\"\n \n required_providers {\n cloudflare = {\n source = \"cloudflare/cloudflare\"\n version = \"~> 5.15.0\"\n }\n }\n}\n\nprovider \"cloudflare\" {\n api_token = var.cloudflare_api_token # or CLOUDFLARE_API_TOKEN env var\n}\n```\n\n### Authentication Methods (priority order)\n\n1. **API Token** (RECOMMENDED): `api_token` or `CLOUDFLARE_API_TOKEN`\n - Create: Dashboard → My Profile → API Tokens\n - Scope to specific accounts/zones for security\n \n2. **Global API Key** (LEGACY): `api_key` + `api_email` or `CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`\n - Less secure, use tokens instead\n \n3. **User Service Key**: `user_service_key` for Origin CA certificates\n\n\n\n## Quick Reference: Common Commands\n\n```bash\nterraform init # Initialize provider\nterraform plan # Plan changes\nterraform apply # Apply changes\nterraform destroy # Destroy resources\nterraform import cloudflare_zone.example # Import existing\nterraform state list # List resources in state\nterraform output # Show outputs\nterraform fmt -recursive # Format code\nterraform validate # Validate configuration\n```\n\n## Import Existing Resources\n\nUse cf-terraforming to generate configs from existing Cloudflare resources:\n\n```bash\n# Install\nbrew install cloudflare/cloudflare/cf-terraforming\n\n# Generate HCL from existing resources\ncf-terraforming generate --resource-type cloudflare_dns_record --zone \n\n# Import into Terraform state\ncf-terraforming import --resource-type cloudflare_dns_record --zone \n```\n\n## Reading Order\n\n1. Start with [README.md](./README.md) for provider setup and authentication\n2. Review [configuration.md](./configuration.md) for resource configurations\n3. Check [api.md](./api.md) for data sources and existing resource queries\n4. See [patterns.md](./patterns.md) for multi-environment and CI/CD patterns\n5. Read [gotchas.md](./gotchas.md) for state drift, v5 breaking changes, and troubleshooting\n\n## In This Reference\n- [configuration.md](./configuration.md) - Resources for zones, DNS, workers, KV, R2, D1, Pages, rulesets\n- [api.md](./api.md) - Data sources for existing resources\n- [patterns.md](./patterns.md) - Architecture patterns, multi-env setup, CI/CD integration\n- [gotchas.md](./gotchas.md) - Common issues, security, best practices\n\n## See Also\n- [pulumi](../pulumi/) - Alternative IaC tool for Cloudflare\n- [wrangler](../wrangler/) - CLI deployment alternative\n- [workers](../workers/) - Worker runtime documentation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/terraform/api.md", "content": "# Terraform Data Sources Reference\n\nQuery existing Cloudflare resources to reference in your configurations.\n\n## v5 Data Source Names\n\n| v4 Name | v5 Name | Notes |\n|---------|---------|-------|\n| `cloudflare_record` | `cloudflare_dns_record` | |\n| `cloudflare_worker_script` | `cloudflare_workers_script` | Note: plural |\n| `cloudflare_access_*` | `cloudflare_zero_trust_*` | Access → Zero Trust |\n\n## Zone Data Sources\n\n```hcl\n# Get zone by name\ndata \"cloudflare_zone\" \"example\" {\n name = \"example.com\"\n}\n\n# Use in resources\nresource \"cloudflare_dns_record\" \"www\" {\n zone_id = data.cloudflare_zone.example.id\n name = \"www\"\n # ...\n}\n```\n\n## Account Data Sources\n\n```hcl\n# List all accounts\ndata \"cloudflare_accounts\" \"main\" {\n name = \"My Account\"\n}\n\n# Use account ID\nresource \"cloudflare_worker_script\" \"api\" {\n account_id = data.cloudflare_accounts.main.accounts[0].id\n # ...\n}\n```\n\n## Worker Data Sources\n\n```hcl\n# Get existing worker script (v5: cloudflare_workers_script)\ndata \"cloudflare_workers_script\" \"existing\" {\n account_id = var.account_id\n name = \"existing-worker\"\n}\n\n# Reference in service bindings\nresource \"cloudflare_workers_script\" \"consumer\" {\n service_binding {\n name = \"UPSTREAM\"\n service = data.cloudflare_workers_script.existing.name\n }\n}\n```\n\n## KV Data Sources\n\n```hcl\n# Get KV namespace\ndata \"cloudflare_workers_kv_namespace\" \"existing\" {\n account_id = var.account_id\n namespace_id = \"abc123\"\n}\n\n# Use in worker binding\nresource \"cloudflare_workers_script\" \"api\" {\n kv_namespace_binding {\n name = \"KV\"\n namespace_id = data.cloudflare_workers_kv_namespace.existing.id\n }\n}\n```\n\n## Lists Data Source\n\n```hcl\n# Get IP lists for WAF rules\ndata \"cloudflare_list\" \"blocked_ips\" {\n account_id = var.account_id\n name = \"blocked_ips\"\n}\n```\n\n## IP Ranges Data Source\n\n```hcl\n# Get Cloudflare IP ranges (for firewall rules)\ndata \"cloudflare_ip_ranges\" \"cloudflare\" {}\n\noutput \"ipv4_cidrs\" {\n value = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks\n}\n\noutput \"ipv6_cidrs\" {\n value = data.cloudflare_ip_ranges.cloudflare.ipv6_cidr_blocks\n}\n\n# Use in security group rules (AWS example)\nresource \"aws_security_group_rule\" \"allow_cloudflare\" {\n type = \"ingress\"\n from_port = 443\n to_port = 443\n protocol = \"tcp\"\n cidr_blocks = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks\n security_group_id = aws_security_group.web.id\n}\n```\n\n## Common Patterns\n\n### Import ID Formats\n\n| Resource | Import ID Format |\n|----------|------------------|\n| `cloudflare_zone` | `` |\n| `cloudflare_dns_record` | `/` |\n| `cloudflare_workers_script` | `/` |\n| `cloudflare_workers_kv_namespace` | `/` |\n| `cloudflare_r2_bucket` | `/` |\n| `cloudflare_d1_database` | `/` |\n| `cloudflare_pages_project` | `/` |\n\n```bash\n# Example: Import DNS record\nterraform import cloudflare_dns_record.example /\n```\n\n### Reference Across Modules\n\n```hcl\n# modules/worker/main.tf\ndata \"cloudflare_zone\" \"main\" {\n name = var.domain\n}\n\nresource \"cloudflare_worker_route\" \"api\" {\n zone_id = data.cloudflare_zone.main.id\n pattern = \"api.${var.domain}/*\"\n script_name = cloudflare_worker_script.api.name\n}\n```\n\n### Output Important Values\n\n```hcl\noutput \"zone_id\" {\n value = cloudflare_zone.main.id\n description = \"Zone ID for DNS management\"\n}\n\noutput \"worker_url\" {\n value = \"https://${cloudflare_worker_domain.api.hostname}\"\n description = \"Worker API endpoint\"\n}\n\noutput \"kv_namespace_id\" {\n value = cloudflare_workers_kv_namespace.app.id\n sensitive = false\n}\n\noutput \"name_servers\" {\n value = cloudflare_zone.main.name_servers\n description = \"Name servers for domain registration\"\n}\n```\n\n## See Also\n\n- [README](./README.md) - Provider setup\n- [Configuration Reference](./configuration.md) - All resource types\n- [Patterns](./patterns.md) - Architecture patterns\n- [Troubleshooting](./gotchas.md) - Common issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/terraform/configuration.md", "content": "# Terraform Configuration Reference\n\nComplete resource configurations for Cloudflare infrastructure.\n\n## Zone & DNS\n\n```hcl\n# Zone + settings\nresource \"cloudflare_zone\" \"example\" { account = { id = var.account_id }; name = \"example.com\"; type = \"full\" }\nresource \"cloudflare_zone_settings_override\" \"example\" {\n zone_id = cloudflare_zone.example.id\n settings { ssl = \"strict\"; always_use_https = \"on\"; min_tls_version = \"1.2\"; tls_1_3 = \"on\"; http3 = \"on\" }\n}\n\n# DNS records (A, CNAME, MX, TXT)\nresource \"cloudflare_dns_record\" \"www\" {\n zone_id = cloudflare_zone.example.id; name = \"www\"; content = \"192.0.2.1\"; type = \"A\"; proxied = true\n}\nresource \"cloudflare_dns_record\" \"mx\" {\n for_each = { \"10\" = \"mail1.example.com\", \"20\" = \"mail2.example.com\" }\n zone_id = cloudflare_zone.example.id; name = \"@\"; content = each.value; type = \"MX\"; priority = each.key\n}\n```\n\n## Workers\n\n### Simple Pattern (Legacy - Still Works)\n\n```hcl\nresource \"cloudflare_workers_script\" \"api\" {\n account_id = var.account_id; name = \"api-worker\"; content = file(\"worker.js\")\n module = true; compatibility_date = \"2025-01-01\"\n kv_namespace_binding { name = \"KV\"; namespace_id = cloudflare_workers_kv_namespace.cache.id }\n r2_bucket_binding { name = \"BUCKET\"; bucket_name = cloudflare_r2_bucket.assets.name }\n d1_database_binding { name = \"DB\"; database_id = cloudflare_d1_database.app.id }\n secret_text_binding { name = \"SECRET\"; text = var.secret }\n}\n```\n\n### Gradual Rollouts (Recommended for Production)\n\n```hcl\nresource \"cloudflare_worker\" \"api\" { account_id = var.account_id; name = \"api-worker\" }\nresource \"cloudflare_worker_version\" \"api_v1\" {\n account_id = var.account_id; worker_name = cloudflare_worker.api.name\n content = file(\"worker.js\"); content_sha256 = filesha256(\"worker.js\")\n compatibility_date = \"2025-01-01\"\n bindings {\n kv_namespace { name = \"KV\"; namespace_id = cloudflare_workers_kv_namespace.cache.id }\n r2_bucket { name = \"BUCKET\"; bucket_name = cloudflare_r2_bucket.assets.name }\n }\n}\nresource \"cloudflare_workers_deployment\" \"api\" {\n account_id = var.account_id; worker_name = cloudflare_worker.api.name\n versions { version_id = cloudflare_worker_version.api_v1.id; percentage = 100 }\n}\n```\n\n### Worker Binding Types (v5)\n\n| Binding | Attribute | Example |\n|---------|-----------|---------|\n| KV | `kv_namespace_binding` | `{ name = \"KV\", namespace_id = \"...\" }` |\n| R2 | `r2_bucket_binding` | `{ name = \"BUCKET\", bucket_name = \"...\" }` |\n| D1 | `d1_database_binding` | `{ name = \"DB\", database_id = \"...\" }` |\n| Service | `service_binding` | `{ name = \"AUTH\", service = \"auth-worker\" }` |\n| Secret | `secret_text_binding` | `{ name = \"API_KEY\", text = \"...\" }` |\n| Queue | `queue_binding` | `{ name = \"QUEUE\", queue_name = \"...\" }` |\n| Vectorize | `vectorize_binding` | `{ name = \"INDEX\", index_name = \"...\" }` |\n| Hyperdrive | `hyperdrive_binding` | `{ name = \"DB\", id = \"...\" }` |\n| AI | `ai_binding` | `{ name = \"AI\" }` |\n| Browser | `browser_binding` | `{ name = \"BROWSER\" }` |\n| Analytics | `analytics_engine_binding` | `{ name = \"ANALYTICS\", dataset = \"...\" }` |\n| mTLS | `mtls_certificate_binding` | `{ name = \"CERT\", certificate_id = \"...\" }` |\n\n### Routes & Triggers\n\n```hcl\nresource \"cloudflare_worker_route\" \"api\" {\n zone_id = cloudflare_zone.example.id; pattern = \"api.example.com/*\"\n script_name = cloudflare_workers_script.api.name\n}\nresource \"cloudflare_worker_cron_trigger\" \"task\" {\n account_id = var.account_id; script_name = cloudflare_workers_script.api.name\n schedules = [\"*/5 * * * *\"]\n}\n```\n\n## Storage (KV, R2, D1)\n\n```hcl\n# KV\nresource \"cloudflare_workers_kv_namespace\" \"cache\" { account_id = var.account_id; title = \"cache\" }\nresource \"cloudflare_workers_kv\" \"config\" {\n account_id = var.account_id; namespace_id = cloudflare_workers_kv_namespace.cache.id\n key_name = \"config\"; value = jsonencode({ version = \"1.0\" })\n}\n\n# R2\nresource \"cloudflare_r2_bucket\" \"assets\" { account_id = var.account_id; name = \"assets\"; location = \"WNAM\" }\n\n# D1 (migrations via wrangler) & Queues\nresource \"cloudflare_d1_database\" \"app\" { account_id = var.account_id; name = \"app-db\" }\nresource \"cloudflare_queue\" \"events\" { account_id = var.account_id; name = \"events-queue\" }\n```\n\n## Pages\n\n```hcl\nresource \"cloudflare_pages_project\" \"site\" {\n account_id = var.account_id; name = \"site\"; production_branch = \"main\"\n deployment_configs {\n production {\n compatibility_date = \"2025-01-01\"\n environment_variables = { NODE_ENV = \"production\" }\n kv_namespaces = { KV = cloudflare_workers_kv_namespace.cache.id }\n d1_databases = { DB = cloudflare_d1_database.app.id }\n }\n }\n build_config { build_command = \"npm run build\"; destination_dir = \"dist\" }\n source { type = \"github\"; config { owner = \"org\"; repo_name = \"site\"; production_branch = \"main\" }}\n}\n\nresource \"cloudflare_pages_domain\" \"custom\" {\n account_id = var.account_id; project_name = cloudflare_pages_project.site.name; domain = \"site.example.com\"\n}\n```\n\n## Rulesets (WAF, Redirects, Cache)\n\n```hcl\n# WAF\nresource \"cloudflare_ruleset\" \"waf\" {\n zone_id = cloudflare_zone.example.id; name = \"WAF\"; kind = \"zone\"; phase = \"http_request_firewall_custom\"\n rules { action = \"block\"; enabled = true; expression = \"(cf.client.bot) and not (cf.verified_bot)\" }\n}\n\n# Redirects\nresource \"cloudflare_ruleset\" \"redirects\" {\n zone_id = cloudflare_zone.example.id; name = \"Redirects\"; kind = \"zone\"; phase = \"http_request_dynamic_redirect\"\n rules {\n action = \"redirect\"; enabled = true; expression = \"(http.request.uri.path eq \\\"/old\\\")\"\n action_parameters { from_value { status_code = 301; target_url { value = \"https://example.com/new\" }}}\n }\n}\n\n# Cache rules\nresource \"cloudflare_ruleset\" \"cache\" {\n zone_id = cloudflare_zone.example.id; name = \"Cache\"; kind = \"zone\"; phase = \"http_request_cache_settings\"\n rules {\n action = \"set_cache_settings\"; enabled = true; expression = \"(http.request.uri.path matches \\\"\\\\.(jpg|png|css|js)$\\\")\"\n action_parameters { cache = true; edge_ttl { mode = \"override_origin\"; default = 86400 }}\n }\n}\n```\n\n## Load Balancers\n\n```hcl\nresource \"cloudflare_load_balancer_monitor\" \"http\" {\n account_id = var.account_id; type = \"http\"; path = \"/health\"; interval = 60; timeout = 5\n}\nresource \"cloudflare_load_balancer_pool\" \"api\" {\n account_id = var.account_id; name = \"api-pool\"; monitor = cloudflare_load_balancer_monitor.http.id\n origins { name = \"api-1\"; address = \"192.0.2.1\" }\n origins { name = \"api-2\"; address = \"192.0.2.2\" }\n}\nresource \"cloudflare_load_balancer\" \"api\" {\n zone_id = cloudflare_zone.example.id; name = \"api.example.com\"\n default_pool_ids = [cloudflare_load_balancer_pool.api.id]; steering_policy = \"geo\"\n}\n```\n\n## Access (Zero Trust)\n\n```hcl\nresource \"cloudflare_access_application\" \"admin\" {\n account_id = var.account_id; name = \"Admin\"; domain = \"admin.example.com\"; type = \"self_hosted\"\n session_duration = \"24h\"; allowed_idps = [cloudflare_access_identity_provider.github.id]\n}\nresource \"cloudflare_access_policy\" \"allow\" {\n account_id = var.account_id; application_id = cloudflare_access_application.admin.id\n name = \"Allow\"; decision = \"allow\"; precedence = 1\n include { email = [\"admin@example.com\"] }\n}\nresource \"cloudflare_access_identity_provider\" \"github\" {\n account_id = var.account_id; name = \"GitHub\"; type = \"github\"\n config { client_id = var.github_id; client_secret = var.github_secret }\n}\n```\n\n## See Also\n\n- [README](./README.md) - Provider setup\n- [API](./api.md) - Data sources\n- [Patterns](./patterns.md) - Use cases\n- [Troubleshooting](./gotchas.md) - Issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/terraform/gotchas.md", "content": "# Terraform Troubleshooting & Best Practices\n\nCommon issues, security considerations, and best practices.\n\n## State Drift Issues\n\nSome resources have known state drift. Add lifecycle blocks to prevent perpetual diffs:\n\n| Resource | Drift Attributes | Workaround |\n|----------|------------------|------------|\n| `cloudflare_pages_project` | `deployment_configs.*` | `ignore_changes = [deployment_configs]` |\n| `cloudflare_workers_script` | secrets returned as REDACTED | `ignore_changes = [secret_text_binding]` |\n| `cloudflare_load_balancer` | `adaptive_routing`, `random_steering` | `ignore_changes = [adaptive_routing, random_steering]` |\n| `cloudflare_workers_kv` | special chars in keys (< 5.16.0) | Upgrade to 5.16.0+ |\n\n```hcl\n# Example: Ignore secret drift\nresource \"cloudflare_workers_script\" \"api\" {\n account_id = var.account_id\n name = \"api-worker\"\n content = file(\"worker.js\")\n secret_text_binding { name = \"API_KEY\"; text = var.api_key }\n \n lifecycle {\n ignore_changes = [secret_text_binding]\n }\n}\n```\n\n## v5 Breaking Changes\n\nProvider v5 is current (auto-generated from OpenAPI). v4→v5 has breaking changes:\n\n**Resource Renames:**\n\n| v4 Resource | v5 Resource | Notes |\n|-------------|-------------|-------|\n| `cloudflare_record` | `cloudflare_dns_record` | |\n| `cloudflare_worker_script` | `cloudflare_workers_script` | Note: plural |\n| `cloudflare_worker_*` | `cloudflare_workers_*` | All worker resources |\n| `cloudflare_access_*` | `cloudflare_zero_trust_*` | Access → Zero Trust |\n\n**Attribute Changes:**\n\n| v4 Attribute | v5 Attribute | Resources |\n|--------------|--------------|-----------|\n| `zone` | `name` | zone |\n| `account_id` | `account.id` | zone (object syntax) |\n| `key` | `key_name` | KV |\n| `location_hint` | `location` | R2 |\n\n**State Migration:**\n\n```bash\n# Rename resources in state after v5 upgrade\nterraform state mv cloudflare_record.example cloudflare_dns_record.example\nterraform state mv cloudflare_worker_script.api cloudflare_workers_script.api\n```\n\n## Resource-Specific Gotchas\n\n### R2 Location Case Sensitivity\n\n**Problem:** Terraform creates R2 bucket but fails on subsequent applies \n**Cause:** Location must be UPPERCASE \n**Solution:** Use `WNAM`, `ENAM`, `WEUR`, `EEUR`, `APAC` (not `wnam`, `enam`, etc.)\n\n```hcl\nresource \"cloudflare_r2_bucket\" \"assets\" {\n account_id = var.account_id\n name = \"assets\"\n location = \"WNAM\" # UPPERCASE required\n}\n```\n\n### KV Special Characters (< 5.16.0)\n\n**Problem:** Keys with `+`, `#`, `%` cause encoding issues \n**Cause:** URL encoding bug in provider < 5.16.0 \n**Solution:** Upgrade to 5.16.0+ or avoid special chars in keys\n\n### D1 Migrations\n\n**Problem:** Terraform creates database but schema is empty \n**Cause:** Terraform only creates D1 resource, not schema \n**Solution:** Run migrations via wrangler after Terraform apply\n\n```bash\n# After terraform apply\nwrangler d1 migrations apply \n```\n\n### Worker Script Size Limit\n\n**Problem:** Worker deployment fails with \"script too large\" \n**Cause:** Worker script + dependencies exceed 10 MB limit \n**Solution:** Use code splitting, external dependencies, or minification\n\n### Pages Project Drift\n\n**Problem:** Pages project shows perpetual diff on `deployment_configs` \n**Cause:** Cloudflare API adds default values not in Terraform state \n**Solution:** Add lifecycle ignore block (see State Drift table above)\n\n## Common Errors\n\n### \"Error: couldn't find resource\"\n\n**Cause:** Resource was deleted outside Terraform \n**Solution:** Import resource back into state with `terraform import cloudflare_zone.example ` or remove from state with `terraform state rm cloudflare_zone.example`\n\n### \"409 Conflict on worker deployment\"\n\n**Cause:** Worker being deployed by both Terraform and wrangler simultaneously \n**Solution:** Choose one deployment method; if using Terraform, remove wrangler deployments\n\n### \"DNS record already exists\"\n\n**Cause:** Existing DNS record not imported into Terraform state \n**Solution:** Find record ID in Cloudflare dashboard and import with `terraform import cloudflare_dns_record.example /`\n\n### \"Invalid provider configuration\"\n\n**Cause:** API token missing, invalid, or lacking required permissions \n**Solution:** Set `CLOUDFLARE_API_TOKEN` environment variable or check token permissions in dashboard\n\n### \"State locking errors\"\n\n**Cause:** Multiple concurrent Terraform runs or stale lock from crashed process \n**Solution:** Remove stale lock with `terraform force-unlock ` (use with caution)\n\n## Limits\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| API token rate limit | Varies by plan | Use `api_client_logging = true` to debug\n| Worker script size | 10 MB | Includes all dependencies\n| KV keys per namespace | Unlimited | Pay per operation\n| R2 storage | Unlimited | Pay per GB\n| D1 databases | 50,000 per account | Free tier: 10\n| Pages projects | 500 per account | 100 for free accounts\n| DNS records | 3,500 per zone | Free plan\n\n## See Also\n\n- [README](./README.md) - Provider setup\n- [Configuration](./configuration.md) - Resources\n- [API](./api.md) - Data sources\n- [Patterns](./patterns.md) - Use cases\n- Provider docs: https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs\n" }, { "path": "skills/.curated/cloudflare-deploy/references/terraform/patterns.md", "content": "# Terraform Patterns & Use Cases\n\nArchitecture patterns, multi-environment setups, and real-world use cases.\n\n## Recommended Directory Structure\n\n```\nterraform/\n├── environments/\n│ ├── production/\n│ │ ├── main.tf\n│ │ └── terraform.tfvars\n│ └── staging/\n│ ├── main.tf\n│ └── terraform.tfvars\n├── modules/\n│ ├── zone/\n│ ├── worker/\n│ └── dns/\n└── shared/ # Shared resources across envs\n └── main.tf\n```\n\n**Note:** Cloudflare recommends avoiding modules for provider resources due to v5 auto-generation complexity. Prefer environment directories + shared state instead.\n\n## Multi-Environment Setup\n\n```hcl\n# Directory: environments/{production,staging}/main.tf + modules/{zone,worker,pages}\nmodule \"zone\" {\n source = \"../../modules/zone\"; account_id = var.account_id; zone_name = \"example.com\"; environment = \"production\"\n}\nmodule \"api_worker\" {\n source = \"../../modules/worker\"; account_id = var.account_id; zone_id = module.zone.zone_id\n name = \"api-worker-prod\"; script = file(\"../../workers/api.js\"); environment = \"production\"\n}\n```\n\n## R2 State Backend\n\n```hcl\nterraform {\n backend \"s3\" {\n bucket = \"terraform-state\"\n key = \"cloudflare.tfstate\"\n region = \"auto\"\n endpoints = { s3 = \"https://.r2.cloudflarestorage.com\" }\n skip_credentials_validation = true\n skip_region_validation = true\n skip_requesting_account_id = true\n skip_metadata_api_check = true\n skip_s3_checksum = true\n }\n}\n```\n\n## Worker with All Bindings\n\n```hcl\nlocals { worker_name = \"full-stack-worker\" }\nresource \"cloudflare_workers_kv_namespace\" \"app\" { account_id = var.account_id; title = \"${local.worker_name}-kv\" }\nresource \"cloudflare_r2_bucket\" \"app\" { account_id = var.account_id; name = \"${local.worker_name}-bucket\" }\nresource \"cloudflare_d1_database\" \"app\" { account_id = var.account_id; name = \"${local.worker_name}-db\" }\n\nresource \"cloudflare_worker_script\" \"app\" {\n account_id = var.account_id; name = local.worker_name; content = file(\"worker.js\"); module = true\n compatibility_date = \"2025-01-01\"\n kv_namespace_binding { name = \"KV\"; namespace_id = cloudflare_workers_kv_namespace.app.id }\n r2_bucket_binding { name = \"BUCKET\"; bucket_name = cloudflare_r2_bucket.app.name }\n d1_database_binding { name = \"DB\"; database_id = cloudflare_d1_database.app.id }\n secret_text_binding { name = \"API_KEY\"; text = var.api_key }\n}\n```\n\n## Wrangler Integration\n\n**CRITICAL**: Wrangler and Terraform must NOT manage same resources.\n\n**Terraform**: Zones, DNS, security rules, Access, load balancers, worker deployments (CI/CD), KV/R2/D1 resource creation \n**Wrangler**: Local dev (`wrangler dev`), manual deploys, D1 migrations, KV bulk ops, log streaming (`wrangler tail`)\n\n### CI/CD Pattern\n\n```hcl\n# Terraform creates infrastructure\nresource \"cloudflare_workers_kv_namespace\" \"app\" { account_id = var.account_id; title = \"app-kv\" }\nresource \"cloudflare_d1_database\" \"app\" { account_id = var.account_id; name = \"app-db\" }\noutput \"kv_namespace_id\" { value = cloudflare_workers_kv_namespace.app.id }\noutput \"d1_database_id\" { value = cloudflare_d1_database.app.id }\n```\n\n```yaml\n# GitHub Actions: terraform apply → envsubst wrangler.jsonc.template → wrangler deploy\n- run: terraform apply -auto-approve\n- run: |\n export KV_NAMESPACE_ID=$(terraform output -raw kv_namespace_id)\n envsubst < wrangler.jsonc.template > wrangler.jsonc\n- run: wrangler deploy\n```\n\n## Use Cases\n\n### Static Site + API Worker\n\n```hcl\nresource \"cloudflare_pages_project\" \"frontend\" {\n account_id = var.account_id; name = \"frontend\"; production_branch = \"main\"\n build_config { build_command = \"npm run build\"; destination_dir = \"dist\" }\n}\nresource \"cloudflare_worker_script\" \"api\" {\n account_id = var.account_id; name = \"api\"; content = file(\"api-worker.js\")\n d1_database_binding { name = \"DB\"; database_id = cloudflare_d1_database.api_db.id }\n}\nresource \"cloudflare_dns_record\" \"frontend\" {\n zone_id = cloudflare_zone.main.id; name = \"app\"; content = cloudflare_pages_project.frontend.subdomain; type = \"CNAME\"; proxied = true\n}\nresource \"cloudflare_worker_route\" \"api\" {\n zone_id = cloudflare_zone.main.id; pattern = \"api.example.com/*\"; script_name = cloudflare_worker_script.api.name\n}\n```\n\n### Multi-Region Load Balancing\n\n```hcl\nresource \"cloudflare_load_balancer_pool\" \"us\" {\n account_id = var.account_id; name = \"us-pool\"; monitor = cloudflare_load_balancer_monitor.http.id\n origins { name = \"us-east\"; address = var.us_east_ip }\n}\nresource \"cloudflare_load_balancer_pool\" \"eu\" {\n account_id = var.account_id; name = \"eu-pool\"; monitor = cloudflare_load_balancer_monitor.http.id\n origins { name = \"eu-west\"; address = var.eu_west_ip }\n}\nresource \"cloudflare_load_balancer\" \"global\" {\n zone_id = cloudflare_zone.main.id; name = \"api.example.com\"; steering_policy = \"geo\"\n default_pool_ids = [cloudflare_load_balancer_pool.us.id]\n region_pools { region = \"WNAM\"; pool_ids = [cloudflare_load_balancer_pool.us.id] }\n region_pools { region = \"WEU\"; pool_ids = [cloudflare_load_balancer_pool.eu.id] }\n}\n```\n\n### Secure Admin with Access\n\n```hcl\nresource \"cloudflare_pages_project\" \"admin\" { account_id = var.account_id; name = \"admin\"; production_branch = \"main\" }\nresource \"cloudflare_access_application\" \"admin\" {\n account_id = var.account_id; name = \"Admin\"; domain = \"admin.example.com\"; type = \"self_hosted\"; session_duration = \"24h\"\n allowed_idps = [cloudflare_access_identity_provider.google.id]\n}\nresource \"cloudflare_access_policy\" \"allow\" {\n account_id = var.account_id; application_id = cloudflare_access_application.admin.id\n name = \"Allow admins\"; decision = \"allow\"; precedence = 1; include { email = var.admin_emails }\n}\n```\n\n### Reusable Module\n\n```hcl\n# modules/cloudflare-zone/main.tf\nvariable \"account_id\" { type = string }; variable \"domain\" { type = string }; variable \"ssl_mode\" { default = \"strict\" }\nresource \"cloudflare_zone\" \"main\" { account = { id = var.account_id }; name = var.domain }\nresource \"cloudflare_zone_settings_override\" \"main\" {\n zone_id = cloudflare_zone.main.id; settings { ssl = var.ssl_mode; always_use_https = \"on\" }\n}\noutput \"zone_id\" { value = cloudflare_zone.main.id }\n\n# Usage: module \"prod\" { source = \"./modules/cloudflare-zone\"; account_id = var.account_id; domain = \"example.com\" }\n```\n\n## See Also\n\n- [README](./README.md) - Provider setup\n- [Configuration Reference](./configuration.md) - All resource types\n- [API Reference](./api.md) - Data sources\n- [Troubleshooting](./gotchas.md) - Best practices, common issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/README.md", "content": "# Cloudflare Tunnel\n\nSecure outbound-only connections between infrastructure and Cloudflare's global network.\n\n## Overview\n\nCloudflare Tunnel (formerly Argo Tunnel) enables:\n- **Outbound-only connections** - No inbound ports or firewall changes\n- **Public hostname routing** - Expose local services to internet\n- **Private network access** - Connect internal networks via WARP\n- **Zero Trust integration** - Built-in access policies\n\n**Architecture**: Tunnel (persistent object) → Replica (`cloudflared` process) → Origin services\n\n**Terminology:**\n- **Tunnel**: Named persistent object with UUID\n- **Replica**: Individual `cloudflared` process connected to tunnel\n- **Config Source**: Where ingress rules stored (local file vs Cloudflare dashboard)\n- **Connector**: Legacy term for replica\n\n## Quick Start\n\n### Local Config\n```bash\n# Install cloudflared\nbrew install cloudflared # macOS\n\n# Authenticate\ncloudflared tunnel login\n\n# Create tunnel\ncloudflared tunnel create my-tunnel\n\n# Route DNS\ncloudflared tunnel route dns my-tunnel app.example.com\n\n# Run tunnel\ncloudflared tunnel run my-tunnel\n```\n\n### Dashboard Config (Recommended)\n1. **Zero Trust** > **Networks** > **Tunnels** > **Create**\n2. Name tunnel, copy token\n3. Configure routes in dashboard\n4. Run: `cloudflared tunnel --no-autoupdate run --token `\n\n## Decision Tree\n\n**Choose config source:**\n```\nNeed centralized config updates?\n├─ Yes → Token-based (dashboard config)\n└─ No → Local config file\n\nMultiple environments (dev/staging/prod)?\n├─ Yes → Local config (version controlled)\n└─ No → Either works\n\nNeed firewall approval?\n└─ See networking.md first\n```\n\n## Core Commands\n\n```bash\n# Tunnel lifecycle\ncloudflared tunnel create \ncloudflared tunnel list\ncloudflared tunnel info \ncloudflared tunnel delete \n\n# DNS routing\ncloudflared tunnel route dns \ncloudflared tunnel route list\n\n# Private network\ncloudflared tunnel route ip add 10.0.0.0/8 \n\n# Run tunnel\ncloudflared tunnel run \n```\n\n## Configuration Example\n\n```yaml\n# ~/.cloudflared/config.yml\ntunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef\ncredentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json\n\ningress:\n - hostname: app.example.com\n service: http://localhost:8000\n - hostname: api.example.com\n service: https://localhost:8443\n originRequest:\n noTLSVerify: true\n - service: http_status:404\n```\n\n## Reading Order\n\n**New to Cloudflare Tunnel:**\n1. This README (overview, quick start)\n2. [networking.md](./networking.md) - Firewall rules, connectivity pre-checks\n3. [configuration.md](./configuration.md) - Config file options, ingress rules\n4. [patterns.md](./patterns.md) - Docker, Kubernetes, production deployment\n5. [gotchas.md](./gotchas.md) - Troubleshooting, best practices\n\n**Enterprise deployment:**\n1. [networking.md](./networking.md) - Corporate firewall requirements\n2. [gotchas.md](./gotchas.md) - HA setup, security best practices\n3. [patterns.md](./patterns.md) - Kubernetes, rolling updates\n\n**Programmatic control:**\n1. [api.md](./api.md) - REST API, TypeScript SDK\n\n## In This Reference\n\n- [networking.md](./networking.md) - Firewall rules, ports, connectivity pre-checks\n- [configuration.md](./configuration.md) - Config file options, ingress rules, TLS settings\n- [api.md](./api.md) - REST API, TypeScript SDK, token-based tunnels\n- [patterns.md](./patterns.md) - Docker, Kubernetes, Terraform, HA, use cases\n- [gotchas.md](./gotchas.md) - Troubleshooting, limitations, best practices\n\n## See Also\n\n- [workers](../workers/) - Workers with Tunnel integration\n- [access](../access/) - Zero Trust access policies\n- [warp](../warp/) - WARP client for private networks\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/api.md", "content": "# Tunnel API\n\n## Cloudflare API Access\n\n**Base URL**: `https://api.cloudflare.com/client/v4`\n\n**Authentication**:\n```bash\nAuthorization: Bearer ${CF_API_TOKEN}\n```\n\n## TypeScript SDK\n\nInstall: `npm install cloudflare`\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst cf = new Cloudflare({\n apiToken: process.env.CF_API_TOKEN,\n});\n\nconst accountId = process.env.CF_ACCOUNT_ID;\n```\n\n## Create Tunnel\n\n### cURL\n```bash\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"my-tunnel\",\n \"tunnel_secret\": \"\"\n }'\n```\n\n### TypeScript\n```typescript\nconst tunnel = await cf.zeroTrust.tunnels.create({\n account_id: accountId,\n name: 'my-tunnel',\n tunnel_secret: Buffer.from(crypto.randomBytes(32)).toString('base64'),\n});\n\nconsole.log(`Tunnel ID: ${tunnel.id}`);\n```\n\n## List Tunnels\n\n### cURL\n```bash\ncurl -X GET \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\"\n```\n\n### TypeScript\n```typescript\nconst tunnels = await cf.zeroTrust.tunnels.list({\n account_id: accountId,\n});\n\nfor (const tunnel of tunnels.result) {\n console.log(`${tunnel.name}: ${tunnel.id}`);\n}\n```\n\n## Get Tunnel Info\n\n### cURL\n```bash\ncurl -X GET \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\"\n```\n\n### TypeScript\n```typescript\nconst tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {\n account_id: accountId,\n});\n\nconsole.log(`Status: ${tunnel.status}`);\nconsole.log(`Connections: ${tunnel.connections?.length || 0}`);\n```\n\n## Update Tunnel Config\n\n### cURL\n```bash\ncurl -X PUT \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/configurations\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\" \\\n -H \"Content-Type: application/json\" \\\n --data '{\n \"config\": {\n \"ingress\": [\n {\"hostname\": \"app.example.com\", \"service\": \"http://localhost:8000\"},\n {\"service\": \"http_status:404\"}\n ]\n }\n }'\n```\n\n### TypeScript\n```typescript\nconst config = await cf.zeroTrust.tunnels.configurations.update(\n tunnelId,\n {\n account_id: accountId,\n config: {\n ingress: [\n { hostname: 'app.example.com', service: 'http://localhost:8000' },\n { service: 'http_status:404' },\n ],\n },\n }\n);\n```\n\n## Delete Tunnel\n\n### cURL\n```bash\ncurl -X DELETE \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\"\n```\n\n### TypeScript\n```typescript\nawait cf.zeroTrust.tunnels.delete(tunnelId, {\n account_id: accountId,\n});\n```\n\n## Token-Based Tunnels (Config Source: Cloudflare)\n\nToken-based tunnels store config in Cloudflare dashboard instead of local files.\n\n### Via Dashboard\n1. **Zero Trust** > **Networks** > **Tunnels**\n2. **Create a tunnel** > **Cloudflared**\n3. Configure routes in dashboard\n4. Copy token\n5. Run on origin:\n```bash\ncloudflared service install \n```\n\n### Via Token\n```bash\n# Run with token (no config file needed)\ncloudflared tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}\n\n# Docker\ndocker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}\n```\n\n### Get Tunnel Token (TypeScript)\n```typescript\n// Get tunnel to retrieve token\nconst tunnel = await cf.zeroTrust.tunnels.get(tunnelId, {\n account_id: accountId,\n});\n\n// Token available in tunnel.token (only for config source: cloudflare)\nconst token = tunnel.token;\n```\n\n## DNS Routes API\n\n```bash\n# Create DNS route\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\" \\\n --data '{\"hostname\": \"app.example.com\"}'\n\n# Delete route\ncurl -X DELETE \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/connections/{route_id}\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\"\n```\n\n## Private Network Routes API\n\n```bash\n# Add IP route\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\" \\\n --data '{\"ip_network\": \"10.0.0.0/8\"}'\n\n# List IP routes\ncurl -X GET \"https://api.cloudflare.com/client/v4/accounts/{account_id}/tunnels/{tunnel_id}/routes\" \\\n -H \"Authorization: Bearer ${CF_API_TOKEN}\"\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/configuration.md", "content": "# Tunnel Configuration\n\n## Config Source\n\nTunnels use one of two config sources:\n\n| Config Source | Storage | Updates | Use Case |\n|---------------|---------|---------|----------|\n| Local | `config.yml` file | Edit file, restart | Dev, multi-env, version control |\n| Cloudflare | Dashboard/API | Instant, no restart | Production, centralized management |\n\n**Token-based tunnels** = config source: Cloudflare\n**Locally-managed tunnels** = config source: local\n\n## Config File Location\n\n```\n~/.cloudflared/config.yml # User config\n/etc/cloudflared/config.yml # System-wide (Linux)\n```\n\n## Basic Structure\n\n```yaml\ntunnel: \ncredentials-file: /path/to/.json\n\ningress:\n - hostname: app.example.com\n service: http://localhost:8000\n - service: http_status:404 # Required catch-all\n```\n\n## Ingress Rules\n\nRules evaluated **top to bottom**, first match wins.\n\n```yaml\ningress:\n # Exact hostname + path regex\n - hostname: static.example.com\n path: \\.(jpg|png|css|js)$\n service: https://localhost:8001\n \n # Wildcard hostname\n - hostname: \"*.example.com\"\n service: https://localhost:8002\n \n # Path only (all hostnames)\n - path: /api/.*\n service: http://localhost:9000\n \n # Catch-all (required)\n - service: http_status:404\n```\n\n**Validation**:\n```bash\ncloudflared tunnel ingress validate\ncloudflared tunnel ingress rule https://foo.example.com\n```\n\n## Service Types\n\n| Protocol | Format | Client Requirement |\n|----------|--------|-------------------|\n| HTTP | `http://localhost:8000` | Browser |\n| HTTPS | `https://localhost:8443` | Browser |\n| TCP | `tcp://localhost:2222` | `cloudflared access tcp` |\n| SSH | `ssh://localhost:22` | `cloudflared access ssh` |\n| RDP | `rdp://localhost:3389` | `cloudflared access rdp` |\n| Unix | `unix:/path/to/socket` | Browser |\n| Test | `hello_world` | Browser |\n\n## Origin Configuration\n\n### Connection Settings\n```yaml\noriginRequest:\n connectTimeout: 30s\n tlsTimeout: 10s\n tcpKeepAlive: 30s\n keepAliveTimeout: 90s\n keepAliveConnections: 100\n```\n\n### TLS Settings\n```yaml\noriginRequest:\n noTLSVerify: true # Disable cert verification\n originServerName: \"app.internal\" # Override SNI\n caPool: /path/to/ca.pem # Custom CA\n```\n\n### HTTP Settings\n```yaml\noriginRequest:\n disableChunkedEncoding: true\n httpHostHeader: \"app.internal\"\n http2Origin: true\n```\n\n## Private Network Mode\n\n```yaml\ntunnel: \ncredentials-file: /path/to/creds.json\n\nwarp-routing:\n enabled: true\n```\n\n```bash\ncloudflared tunnel route ip add 10.0.0.0/8 my-tunnel\ncloudflared tunnel route ip add 192.168.1.100/32 my-tunnel\n```\n\n## Config Source Comparison\n\n### Local Config\n```yaml\n# config.yml\ntunnel: \ncredentials-file: /path/to/.json\n\ningress:\n - hostname: app.example.com\n service: http://localhost:8000\n - service: http_status:404\n```\n\n```bash\ncloudflared tunnel run my-tunnel\n```\n\n**Pros:** Version control, multi-environment, offline edits\n**Cons:** Requires file distribution, manual restarts\n\n### Cloudflare Config (Token-Based)\n```bash\n# No config file needed\ncloudflared tunnel --no-autoupdate run --token \n```\n\nConfigure routes in dashboard: **Zero Trust** > **Networks** > **Tunnels** > [Tunnel] > **Public Hostname**\n\n**Pros:** Centralized updates, no file management, instant route changes\n**Cons:** Requires dashboard/API access, less portable\n\n## Environment Variables\n\n```bash\nTUNNEL_TOKEN= # Token for config source: cloudflare\nTUNNEL_ORIGIN_CERT=/path/to/cert.pem # Override cert path (local config)\nNO_AUTOUPDATE=true # Disable auto-updates\nTUNNEL_LOGLEVEL=debug # Log level\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/gotchas.md", "content": "# Tunnel Gotchas\n\n## Common Errors\n\n### \"Error 1016 (Origin DNS Error)\"\n\n**Cause:** Tunnel not running or not connected\n**Solution:**\n```bash\ncloudflared tunnel info my-tunnel # Check status\nps aux | grep cloudflared # Verify running\njournalctl -u cloudflared -n 100 # Check logs\n```\n\n### \"Self-signed certificate rejected\"\n\n**Cause:** Origin using self-signed certificate\n**Solution:**\n```yaml\noriginRequest:\n noTLSVerify: true # Dev only\n caPool: /path/to/ca.pem # Custom CA\n```\n\n### \"Connection timeout\"\n\n**Cause:** Origin slow to respond or timeout settings too low\n**Solution:**\n```yaml\noriginRequest:\n connectTimeout: 60s\n tlsTimeout: 20s\n keepAliveTimeout: 120s\n```\n\n### \"Tunnel not starting\"\n\n**Cause:** Invalid config, missing credentials, or tunnel doesn't exist\n**Solution:**\n```bash\ncloudflared tunnel ingress validate # Validate config\nls -la ~/.cloudflared/*.json # Verify credentials\ncloudflared tunnel list # Verify tunnel exists\n```\n\n### \"Connection already registered\"\n\n**Cause:** Multiple replicas with same connector ID or stale connection\n**Solution:**\n```bash\n# Check active connections\ncloudflared tunnel info my-tunnel\n\n# Wait 60s for stale connection cleanup, or restart with new connector ID\ncloudflared tunnel run my-tunnel\n```\n\n### \"Tunnel credentials rotated but connections fail\"\n\n**Cause:** Old cloudflared processes using expired credentials\n**Solution:**\n```bash\n# Stop all cloudflared processes\npkill cloudflared\n\n# Verify stopped\nps aux | grep cloudflared\n\n# Restart with new credentials\ncloudflared tunnel run my-tunnel\n```\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Free tier | Unlimited tunnels | Unlimited traffic |\n| Tunnel replicas | 1000 per tunnel | Max concurrent |\n| Connection duration | No hard limit | Hours to days |\n| Long-lived connections | May drop during updates | WebSocket, SSH, UDP |\n| Replica registration | ~5s TTL | Old replica dropped after 5s no heartbeat |\n| Token rotation grace | 24 hours | Old tokens work during grace period |\n\n## Best Practices\n\n### Security\n1. Use token-based tunnels (config source: cloudflare) for centralized control\n2. Enable Access policies for sensitive services\n3. Rotate tunnel credentials regularly\n4. After rotation: stop all old cloudflared processes within 24h grace period\n5. Verify TLS certs (`noTLSVerify: false`)\n6. Restrict `bastion` service type\n\n### Performance\n1. Run multiple replicas for HA (2-4 typical, load balanced automatically)\n2. Replicas share same tunnel UUID, get unique connector IDs\n3. Place `cloudflared` close to origin (same network)\n4. Use HTTP/2 for gRPC (`http2Origin: true`)\n5. Tune keepalive for long-lived connections\n6. Monitor connection counts\n\n### Configuration\n1. Use environment variables for secrets\n2. Version control config files\n3. Validate before deploying (`cloudflared tunnel ingress validate`)\n4. Test rules (`cloudflared tunnel ingress rule `)\n5. Document rule order (first match wins)\n\n### Operations\n1. Monitor tunnel health in dashboard (shows active replicas)\n2. Set up disconnect alerts (when replica count drops to 0)\n3. Graceful shutdown for config updates\n4. Update replicas in rolling fashion (update 1, wait, update next)\n5. Keep `cloudflared` updated (1 year support window)\n6. Use `--no-autoupdate` in prod; control updates manually\n\n## Debug Mode\n\n```bash\ncloudflared tunnel --loglevel debug run my-tunnel\ncloudflared tunnel ingress rule https://app.example.com\n```\n\n## Migration Strategies\n\n### From Ngrok\n```yaml\n# Ngrok: ngrok http 8000\n# Cloudflare Tunnel:\ningress:\n - hostname: app.example.com\n service: http://localhost:8000\n - service: http_status:404\n```\n\n### From VPN\n```yaml\n# Replace VPN with private network routing\nwarp-routing:\n enabled: true\n```\n\n```bash\ncloudflared tunnel route ip add 10.0.0.0/8 my-tunnel\n```\n\nUsers install WARP client instead of VPN.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/networking.md", "content": "# Tunnel Networking\n\n## Connectivity Requirements\n\n### Outbound Ports\n\nCloudflared requires outbound access on:\n\n| Port | Protocol | Purpose | Required |\n|------|----------|---------|----------|\n| 7844 | TCP/UDP | Primary tunnel protocol (QUIC) | Yes |\n| 443 | TCP | Fallback (HTTP/2) | Yes |\n\n**Network path:**\n```\ncloudflared → edge.argotunnel.com:7844 (preferred)\ncloudflared → region.argotunnel.com:443 (fallback)\n```\n\n### Firewall Rules\n\n#### Minimal (Production)\n```bash\n# Outbound only\nALLOW tcp/udp 7844 to *.argotunnel.com\nALLOW tcp 443 to *.argotunnel.com\n```\n\n#### Full (Recommended)\n```bash\n# Tunnel connectivity\nALLOW tcp/udp 7844 to *.argotunnel.com\nALLOW tcp 443 to *.argotunnel.com\n\n# API access (for token-based tunnels)\nALLOW tcp 443 to api.cloudflare.com\n\n# Updates (optional)\nALLOW tcp 443 to github.com\nALLOW tcp 443 to objects.githubusercontent.com\n```\n\n### IP Ranges\n\nCloudflare Anycast IPs (tunnel endpoints):\n```\n# IPv4\n198.41.192.0/24\n198.41.200.0/24\n\n# IPv6\n2606:4700::/32\n```\n\n**Note:** Use DNS resolution for `*.argotunnel.com` rather than hardcoding IPs. Cloudflare may add edge locations.\n\n## Pre-Flight Check\n\nTest connectivity before deploying:\n\n```bash\n# Test DNS resolution\ndig edge.argotunnel.com +short\n\n# Test port 7844 (QUIC/UDP)\nnc -zvu edge.argotunnel.com 7844\n\n# Test port 443 (HTTP/2 fallback)\nnc -zv edge.argotunnel.com 443\n\n# Test with cloudflared\ncloudflared tunnel --loglevel debug run my-tunnel\n# Look for \"Registered tunnel connection\"\n```\n\n### Common Connectivity Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| \"no such host\" | DNS blocked | Allow port 53 UDP/TCP |\n| \"context deadline exceeded\" | Port 7844 blocked | Allow UDP/TCP 7844 |\n| \"TLS handshake timeout\" | Port 443 blocked | Allow TCP 443, disable SSL inspection |\n\n## Protocol Selection\n\nCloudflared automatically selects protocol:\n\n| Protocol | Port | Priority | Use Case |\n|----------|------|----------|----------|\n| QUIC | 7844 UDP | 1st (preferred) | Low latency, best performance |\n| HTTP/2 | 443 TCP | 2nd (fallback) | QUIC blocked by firewall |\n\n**Force HTTP/2 fallback:**\n```bash\ncloudflared tunnel --protocol http2 run my-tunnel\n```\n\n**Verify active protocol:**\n```bash\ncloudflared tunnel info my-tunnel\n# Shows \"connections\" with protocol type\n```\n\n## Private Network Routing\n\n### WARP Client Requirements\n\nUsers accessing private IPs via WARP need:\n\n```bash\n# Outbound (WARP client)\nALLOW udp 500,4500 to 162.159.*.* (IPsec)\nALLOW udp 2408 to 162.159.*.* (WireGuard)\nALLOW tcp 443 to *.cloudflareclient.com\n```\n\n### Split Tunnel Configuration\n\nRoute only private networks through tunnel:\n\n```yaml\n# warp-routing config\nwarp-routing:\n enabled: true\n```\n\n```bash\n# Add specific routes\ncloudflared tunnel route ip add 10.0.0.0/8 my-tunnel\ncloudflared tunnel route ip add 172.16.0.0/12 my-tunnel\ncloudflared tunnel route ip add 192.168.0.0/16 my-tunnel\n```\n\nWARP users can access these IPs without VPN.\n\n## Network Diagnostics\n\n### Connection Diagnostics\n\n```bash\n# Check edge selection and connection health\ncloudflared tunnel info my-tunnel --output json | jq '.connections[]'\n\n# Enable metrics endpoint\ncloudflared tunnel --metrics localhost:9090 run my-tunnel\ncurl localhost:9090/metrics | grep cloudflared_tunnel\n\n# Test latency\ncurl -w \"time_total: %{time_total}\\n\" -o /dev/null https://myapp.example.com\n```\n\n## Corporate Network Considerations\n\nCloudflared honors proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`).\n\nIf corporate proxy intercepts TLS, add corporate root CA to system trust store.\n\n## Bandwidth and Rate Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Request size | 100 MB | Single HTTP request |\n| Upload speed | No hard limit | Governed by network/plan |\n| Concurrent connections | 1000 per tunnel | Across all replicas |\n| Requests per second | No limit | Subject to DDoS detection |\n\n**Large file transfers:**\nUse R2 or Workers with chunked uploads instead of streaming through tunnel.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/tunnel/patterns.md", "content": "# Tunnel Patterns\n\n## Docker Deployment\n\n### Token-Based (Recommended)\n```yaml\nservices:\n cloudflared:\n image: cloudflare/cloudflared:latest\n command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}\n restart: unless-stopped\n```\n\n### Local Config\n```yaml\nservices:\n cloudflared:\n image: cloudflare/cloudflared:latest\n volumes:\n - ./config.yml:/etc/cloudflared/config.yml:ro\n - ./credentials.json:/etc/cloudflared/credentials.json:ro\n command: tunnel run\n```\n\n## Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: cloudflared\nspec:\n replicas: 2\n selector:\n matchLabels:\n app: cloudflared\n template:\n metadata:\n labels:\n app: cloudflared\n spec:\n containers:\n - name: cloudflared\n image: cloudflare/cloudflared:latest\n args:\n - tunnel\n - --no-autoupdate\n - run\n - --token\n - $(TUNNEL_TOKEN)\n env:\n - name: TUNNEL_TOKEN\n valueFrom:\n secretKeyRef:\n name: tunnel-credentials\n key: token\n```\n\n## High Availability\n\n```yaml\n# Same config on multiple servers\ntunnel: \ncredentials-file: /path/to/creds.json\n\ningress:\n - hostname: app.example.com\n service: http://localhost:8000\n - service: http_status:404\n```\n\nRun same config on multiple machines. Cloudflare automatically load balances. Long-lived connections (WebSocket, SSH) may drop during updates.\n\n## Use Cases\n\n### Web Application\n```yaml\ningress:\n - hostname: myapp.example.com\n service: http://localhost:3000\n - service: http_status:404\n```\n\n### SSH Access\n```yaml\ningress:\n - hostname: ssh.example.com\n service: ssh://localhost:22\n - service: http_status:404\n```\n\nClient: `cloudflared access ssh --hostname ssh.example.com`\n\n### gRPC Service\n```yaml\ningress:\n - hostname: grpc.example.com\n service: http://localhost:50051\n originRequest:\n http2Origin: true\n - service: http_status:404\n```\n\n## Infrastructure as Code\n\n### Terraform\n\n```hcl\nresource \"random_id\" \"tunnel_secret\" {\n byte_length = 32\n}\n\nresource \"cloudflare_tunnel\" \"app\" {\n account_id = var.cloudflare_account_id\n name = \"app-tunnel\"\n secret = random_id.tunnel_secret.b64_std\n}\n\nresource \"cloudflare_tunnel_config\" \"app\" {\n account_id = var.cloudflare_account_id\n tunnel_id = cloudflare_tunnel.app.id\n config {\n ingress_rule {\n hostname = \"app.example.com\"\n service = \"http://localhost:8000\"\n }\n ingress_rule { service = \"http_status:404\" }\n }\n}\n\nresource \"cloudflare_record\" \"app\" {\n zone_id = var.cloudflare_zone_id\n name = \"app\"\n value = cloudflare_tunnel.app.cname\n type = \"CNAME\"\n proxied = true\n}\n\noutput \"tunnel_token\" {\n value = cloudflare_tunnel.app.tunnel_token\n sensitive = true\n}\n```\n\n### Pulumi\n\n```typescript\nimport * as cloudflare from \"@pulumi/cloudflare\";\nimport * as random from \"@pulumi/random\";\n\nconst secret = new random.RandomId(\"secret\", { byteLength: 32 });\n\nconst tunnel = new cloudflare.ZeroTrustTunnelCloudflared(\"tunnel\", {\n accountId: accountId,\n name: \"app-tunnel\",\n secret: secret.b64Std,\n});\n\nconst config = new cloudflare.ZeroTrustTunnelCloudflaredConfig(\"config\", {\n accountId: accountId,\n tunnelId: tunnel.id,\n config: {\n ingressRules: [\n { hostname: \"app.example.com\", service: \"http://localhost:8000\" },\n { service: \"http_status:404\" },\n ],\n },\n});\n\nnew cloudflare.Record(\"dns\", {\n zoneId: zoneId,\n name: \"app\",\n value: tunnel.cname,\n type: \"CNAME\",\n proxied: true,\n});\n```\n\n## Service Installation\n\n### Linux systemd\n```bash\ncloudflared service install\nsystemctl start cloudflared && systemctl enable cloudflared\njournalctl -u cloudflared -f # Logs\n```\n\n### macOS launchd\n```bash\nsudo cloudflared service install\nsudo launchctl start com.cloudflare.cloudflared\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turn/README.md", "content": "# Cloudflare TURN Service\n\nExpert guidance for implementing Cloudflare TURN Service in WebRTC applications.\n\n## Overview\n\nCloudflare TURN (Traversal Using Relays around NAT) Service is a managed relay service for WebRTC applications. TURN acts as a relay point for traffic between WebRTC clients and SFUs, particularly when direct peer-to-peer communication is obstructed by NATs or firewalls. The service runs on Cloudflare's global anycast network across 310+ cities.\n\n## Key Characteristics\n\n- **Anycast Architecture**: Automatically connects clients to the closest Cloudflare location\n- **Global Network**: Available across Cloudflare's entire network (excluding China Network)\n- **Zero Configuration**: No need to manually select regions or servers\n- **Protocol Support**: STUN/TURN over UDP, TCP, and TLS\n- **Free Tier**: Free when used with Cloudflare Calls SFU, otherwise $0.05/GB outbound\n\n## In This Reference\n\n| File | Purpose |\n|------|---------|\n| [api.md](./api.md) | Credentials API, TURN key management, types, constraints |\n| [configuration.md](./configuration.md) | Worker setup, wrangler.jsonc, env vars, IP allowlisting |\n| [patterns.md](./patterns.md) | Implementation patterns, use cases, integration examples |\n| [gotchas.md](./gotchas.md) | Troubleshooting, limits, security, common mistakes |\n\n## Reading Order\n\n| Task | Files to Read | Est. Tokens |\n|------|---------------|-------------|\n| Quick start | README only | ~500 |\n| Generate credentials | README → api | ~1300 |\n| Worker integration | README → configuration → patterns | ~2000 |\n| Debug connection | gotchas | ~700 |\n| Security review | api → gotchas | ~1500 |\n| Enterprise firewall | configuration | ~600 |\n\n## Service Addresses and Ports\n\n### STUN over UDP\n- **Primary**: `stun.cloudflare.com:3478/udp`\n- **Alternate**: `stun.cloudflare.com:53/udp` (blocked by browsers, not recommended)\n\n### TURN over UDP\n- **Primary**: `turn.cloudflare.com:3478/udp`\n- **Alternate**: `turn.cloudflare.com:53/udp` (blocked by browsers)\n\n### TURN over TCP\n- **Primary**: `turn.cloudflare.com:3478/tcp`\n- **Alternate**: `turn.cloudflare.com:80/tcp`\n\n### TURN over TLS\n- **Primary**: `turn.cloudflare.com:5349/tcp`\n- **Alternate**: `turn.cloudflare.com:443/tcp`\n\n## Quick Start\n\n1. **Create TURN key via API**: see [api.md#create-turn-key](./api.md#create-turn-key)\n2. **Generate credentials**: see [api.md#generate-temporary-credentials](./api.md#generate-temporary-credentials)\n3. **Configure Worker**: see [configuration.md#cloudflare-worker-integration](./configuration.md#cloudflare-worker-integration)\n4. **Implement client**: see [patterns.md#basic-turn-configuration-browser](./patterns.md#basic-turn-configuration-browser)\n\n## When to Use TURN\n\n- **Restrictive NATs**: Symmetric NATs that block direct connections\n- **Corporate firewalls**: Environments blocking WebRTC ports\n- **Mobile networks**: Carrier-grade NAT scenarios\n- **Predictable connectivity**: When reliability > efficiency\n\n## Related Cloudflare Services\n\n- **Cloudflare Calls SFU**: Managed Selective Forwarding Unit (TURN free when used with SFU)\n- **Cloudflare Stream**: Video streaming with WHIP/WHEP support\n- **Cloudflare Workers**: Backend for credential generation\n- **Cloudflare KV**: Credential caching\n- **Cloudflare Durable Objects**: Session state management\n\n## Additional Resources\n\n- [Cloudflare Calls Documentation](https://developers.cloudflare.com/calls/)\n- [Cloudflare TURN Service Docs](https://developers.cloudflare.com/realtime/turn/)\n- [Cloudflare API Reference](https://developers.cloudflare.com/api/resources/calls/subresources/turn/)\n- [Orange Meets (Open Source Example)](https://github.com/cloudflare/orange)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turn/api.md", "content": "# TURN API Reference\n\nComplete API documentation for Cloudflare TURN service credentials and key management.\n\n## Authentication\n\nAll endpoints require Cloudflare API token with \"Calls Write\" permission.\n\nBase URL: `https://api.cloudflare.com/client/v4`\n\n## TURN Key Management\n\n### List TURN Keys\n\n```\nGET /accounts/{account_id}/calls/turn_keys\n```\n\n### Get TURN Key Details\n\n```\nGET /accounts/{account_id}/calls/turn_keys/{key_id}\n```\n\n### Create TURN Key\n\n```\nPOST /accounts/{account_id}/calls/turn_keys\nContent-Type: application/json\n\n{\n \"name\": \"my-turn-key\"\n}\n```\n\n**Response includes**:\n- `uid`: Key identifier\n- `key`: The actual secret key (only returned on creation—save immediately)\n- `name`: Human-readable name\n- `created`: ISO 8601 timestamp\n- `modified`: ISO 8601 timestamp\n\n### Update TURN Key\n\n```\nPUT /accounts/{account_id}/calls/turn_keys/{key_id}\nContent-Type: application/json\n\n{\n \"name\": \"updated-name\"\n}\n```\n\n### Delete TURN Key\n\n```\nDELETE /accounts/{account_id}/calls/turn_keys/{key_id}\n```\n\n## Generate Temporary Credentials\n\n```\nPOST https://rtc.live.cloudflare.com/v1/turn/keys/{key_id}/credentials/generate\nAuthorization: Bearer {key_secret}\nContent-Type: application/json\n\n{\n \"ttl\": 86400\n}\n```\n\n### Credential Constraints\n\n| Parameter | Min | Max | Default | Notes |\n|-----------|-----|-----|---------|-------|\n| ttl | 1 | 172800 (48hrs) | varies | API rejects values >172800 |\n\n**CRITICAL**: Maximum TTL is 48 hours (172800 seconds). API will reject requests exceeding this limit.\n\n### Response Schema\n\n```json\n{\n \"iceServers\": {\n \"urls\": [\n \"stun:stun.cloudflare.com:3478\",\n \"turn:turn.cloudflare.com:3478?transport=udp\",\n \"turn:turn.cloudflare.com:3478?transport=tcp\",\n \"turn:turn.cloudflare.com:53?transport=udp\",\n \"turn:turn.cloudflare.com:80?transport=tcp\",\n \"turns:turn.cloudflare.com:5349?transport=tcp\",\n \"turns:turn.cloudflare.com:443?transport=tcp\"\n ],\n \"username\": \"1738035200:user123\",\n \"credential\": \"base64encodedhmac==\"\n }\n}\n```\n\n**Port 53 Warning**: Filter port 53 URLs for browser clients—blocked by Chrome/Firefox. See [gotchas.md](./gotchas.md#using-port-53-in-browsers).\n\n## Revoke Credentials\n\n```\nPOST https://rtc.live.cloudflare.com/v1/turn/keys/{key_id}/credentials/revoke\nAuthorization: Bearer {key_secret}\nContent-Type: application/json\n\n{\n \"username\": \"1738035200:user123\"\n}\n```\n\n**Response**: 204 No Content\n\nBilling stops immediately. Active connection drops after short delay (~seconds).\n\n## TypeScript Types\n\n```typescript\ninterface CloudflareTURNConfig {\n keyId: string;\n keySecret: string;\n ttl?: number; // Max 172800 (48 hours)\n}\n\ninterface TURNCredentialsRequest {\n ttl?: number; // Max 172800 seconds\n}\n\ninterface TURNCredentialsResponse {\n iceServers: {\n urls: string[];\n username: string;\n credential: string;\n };\n}\n\ninterface RTCIceServer {\n urls: string | string[];\n username?: string;\n credential?: string;\n credentialType?: \"password\";\n}\n\ninterface TURNKeyResponse {\n uid: string;\n key: string; // Only present on creation\n name: string;\n created: string;\n modified: string;\n}\n```\n\n## Validation Function\n\n```typescript\nfunction validateRTCIceServer(obj: unknown): obj is RTCIceServer {\n if (!obj || typeof obj !== 'object') {\n return false;\n }\n\n const server = obj as Record;\n\n if (typeof server.urls !== 'string' && !Array.isArray(server.urls)) {\n return false;\n }\n\n if (server.username && typeof server.username !== 'string') {\n return false;\n }\n\n if (server.credential && typeof server.credential !== 'string') {\n return false;\n }\n\n return true;\n}\n```\n\n## Type-Safe Credential Generation\n\n```typescript\nasync function fetchTURNServers(\n config: CloudflareTURNConfig\n): Promise {\n // Validate TTL constraint\n const ttl = config.ttl ?? 3600;\n if (ttl > 172800) {\n throw new Error('TTL cannot exceed 172800 seconds (48 hours)');\n }\n\n const response = await fetch(\n `https://rtc.live.cloudflare.com/v1/turn/keys/${config.keyId}/credentials/generate`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${config.keySecret}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ ttl })\n }\n );\n\n if (!response.ok) {\n throw new Error(`TURN credential generation failed: ${response.status}`);\n }\n\n const data = await response.json();\n \n // Filter port 53 for browser clients\n const filteredUrls = data.iceServers.urls.filter(\n (url: string) => !url.includes(':53')\n );\n\n const iceServers = [\n { urls: 'stun:stun.cloudflare.com:3478' },\n {\n urls: filteredUrls,\n username: data.iceServers.username,\n credential: data.iceServers.credential,\n credentialType: 'password' as const\n }\n ];\n\n // Validate before returning\n if (!iceServers.every(validateRTCIceServer)) {\n throw new Error('Invalid ICE server configuration received');\n }\n\n return iceServers;\n}\n```\n\n## See Also\n\n- [configuration.md](./configuration.md) - Worker setup, environment variables\n- [patterns.md](./patterns.md) - Implementation examples using these APIs\n- [gotchas.md](./gotchas.md) - Security best practices, common mistakes\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turn/configuration.md", "content": "# TURN Configuration\n\nSetup and configuration for Cloudflare TURN service in Workers and applications.\n\n## Environment Variables\n\n```bash\n# .env\nCLOUDFLARE_ACCOUNT_ID=your_account_id\nCLOUDFLARE_API_TOKEN=your_api_token\nTURN_KEY_ID=your_turn_key_id\nTURN_KEY_SECRET=your_turn_key_secret\n```\n\nValidate with zod:\n\n```typescript\nimport { z } from 'zod';\n\nconst envSchema = z.object({\n CLOUDFLARE_ACCOUNT_ID: z.string().min(1),\n CLOUDFLARE_API_TOKEN: z.string().min(1),\n TURN_KEY_ID: z.string().min(1),\n TURN_KEY_SECRET: z.string().min(1)\n});\n\nexport const config = envSchema.parse(process.env);\n```\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"name\": \"turn-credentials-api\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\",\n \"vars\": {\n \"TURN_KEY_ID\": \"your-turn-key-id\" // Non-sensitive, can be in vars\n },\n \"env\": {\n \"production\": {\n \"kv_namespaces\": [\n {\n \"binding\": \"CREDENTIALS_CACHE\",\n \"id\": \"your-kv-namespace-id\"\n }\n ]\n }\n }\n}\n```\n\n**Store secrets separately**:\n```bash\nwrangler secret put TURN_KEY_SECRET\n```\n\n## Cloudflare Worker Integration\n\n### Worker Binding Types\n\n```typescript\ninterface Env {\n TURN_KEY_ID: string;\n TURN_KEY_SECRET: string;\n CREDENTIALS_CACHE?: KVNamespace;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n // See patterns.md for implementation\n }\n}\n```\n\n### Basic Worker Example\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n if (request.url.endsWith('/turn-credentials')) {\n // Validate client auth\n const authHeader = request.headers.get('Authorization');\n if (!authHeader) {\n return new Response('Unauthorized', { status: 401 });\n }\n\n const response = await fetch(\n `https://rtc.live.cloudflare.com/v1/turn/keys/${env.TURN_KEY_ID}/credentials/generate`,\n {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${env.TURN_KEY_SECRET}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ ttl: 3600 })\n }\n );\n\n if (!response.ok) {\n return new Response('Failed to generate credentials', { status: 500 });\n }\n\n const data = await response.json();\n\n // Filter port 53 for browser clients\n const filteredUrls = data.iceServers.urls.filter(\n (url: string) => !url.includes(':53')\n );\n\n return Response.json({\n iceServers: [\n { urls: 'stun:stun.cloudflare.com:3478' },\n {\n urls: filteredUrls,\n username: data.iceServers.username,\n credential: data.iceServers.credential\n }\n ]\n });\n }\n\n return new Response('Not found', { status: 404 });\n }\n};\n```\n\n## IP Allowlisting (Enterprise/Firewall)\n\nFor strict firewalls, allowlist these IPs for `turn.cloudflare.com`:\n\n| Type | Address | Protocol |\n|------|---------|----------|\n| IPv4 | 141.101.90.1/32 | All |\n| IPv4 | 162.159.207.1/32 | All |\n| IPv6 | 2a06:98c1:3200::1/128 | All |\n| IPv6 | 2606:4700:48::1/128 | All |\n\n**IMPORTANT**: These IPs may change with 14-day notice. Monitor DNS:\n\n```bash\n# Check A and AAAA records\ndig turn.cloudflare.com A\ndig turn.cloudflare.com AAAA\n```\n\nSet up automated monitoring to detect IP changes and update allowlists within 14 days.\n\n## IPv6 Support\n\n- **Client-to-TURN**: Both IPv4 and IPv6 supported\n- **Relay addresses**: IPv4 only (no RFC 6156 support)\n- **TCP relaying**: Not supported (RFC 6062)\n\nClients can connect via IPv6, but relayed traffic uses IPv4 addresses.\n\n## TLS Configuration\n\n### Supported TLS Versions\n- TLS 1.1\n- TLS 1.2\n- TLS 1.3\n\n### Recommended Ciphers (TLS 1.3)\n- AEAD-AES128-GCM-SHA256\n- AEAD-AES256-GCM-SHA384\n- AEAD-CHACHA20-POLY1305-SHA256\n\n### Recommended Ciphers (TLS 1.2)\n- ECDHE-ECDSA-AES128-GCM-SHA256\n- ECDHE-RSA-AES128-GCM-SHA256\n- ECDHE-RSA-AES128-SHA (also TLS 1.1)\n- AES128-GCM-SHA256\n\n## See Also\n\n- [api.md](./api.md) - TURN key creation, credential generation API\n- [patterns.md](./patterns.md) - Full Worker implementation patterns\n- [gotchas.md](./gotchas.md) - Security best practices, troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turn/gotchas.md", "content": "# TURN Gotchas & Troubleshooting\n\nCommon mistakes, security best practices, and troubleshooting for Cloudflare TURN.\n\n## Quick Reference\n\n| Issue | Solution | Details |\n|-------|----------|---------|\n| Credentials not working | Check TTL ≤ 48hrs | [See Troubleshooting](#issue-turn-credentials-not-working) |\n| Connection drops after ~48hrs | Implement credential refresh | [See Connection Drops](#issue-connection-drops-after-48-hours) |\n| Port 53 fails in browser | Filter server-side | [See Port 53](#using-port-53-in-browsers) |\n| High packet loss | Check rate limits | [See Rate Limits](#limits-per-turn-allocation) |\n| Connection fails after maintenance | Implement ICE restart | [See ICE Restart](#ice-restart-required-scenarios) |\n\n## Critical Constraints\n\n| Constraint | Value | Consequence if Violated |\n|------------|-------|-------------------------|\n| Max credential TTL | 48 hours (172800s) | API rejects request |\n| Credential revocation delay | ~seconds | Billing stops immediately, connection drops shortly |\n| IP allowlist update window | 14 days (if IPs change) | Connection fails if IPs change |\n| Packet rate | 5-10k pps per allocation | Packet drops |\n| Data rate | 50-100 Mbps per allocation | Packet drops |\n| Unique IP rate | >5 new IPs/sec | Packet drops |\n\n## Limits Per TURN Allocation\n\n**Per user** (not account-wide):\n\n- **IP addresses**: >5 new unique IPs per second\n- **Packet rate**: 5-10k packets per second (inbound/outbound)\n- **Data rate**: 50-100 Mbps (inbound/outbound)\n- **MTU**: No specific limit\n- **Burst rates**: Higher than documented\n\nExceeding limits results in **packet drops**.\n\n## Common Mistakes\n\n### Setting TTL > 48 hours\n\n```typescript\n// ❌ BAD: API will reject\nconst creds = await generate({ ttl: 604800 }); // 7 days\n\n// ✅ GOOD:\nconst creds = await generate({ ttl: 86400 }); // 24 hours\n```\n\n### Hardcoding IPs without monitoring\n\n```typescript\n// ❌ BAD: IPs can change with 14-day notice\nconst iceServers = [{ urls: 'turn:141.101.90.1:3478' }];\n\n// ✅ GOOD: Use DNS\nconst iceServers = [{ urls: 'turn:turn.cloudflare.com:3478' }];\n```\n\n### Using port 53 in browsers\n\n```typescript\n// ❌ BAD: Blocked by Chrome/Firefox\nurls: ['turn:turn.cloudflare.com:53']\n\n// ✅ GOOD: Filter port 53\nurls: urls.filter(url => !url.includes(':53'))\n```\n\n### Not handling credential expiry\n\n```typescript\n// ❌ BAD: Credentials expire but call continues → connection drops\nconst creds = await fetchCreds();\nconst pc = new RTCPeerConnection({ iceServers: creds });\n\n// ✅ GOOD: Refresh before expiry\nsetInterval(() => refreshCredentials(pc), 3000000); // 50 min\n```\n\n### Missing ICE restart support\n\n```typescript\n// ❌ BAD: No recovery from TURN maintenance\npc.addEventListener('iceconnectionstatechange', () => {\n console.log('State changed:', pc.iceConnectionState);\n});\n\n// ✅ GOOD: Implement ICE restart\npc.addEventListener('iceconnectionstatechange', async () => {\n if (pc.iceConnectionState === 'failed') {\n await refreshCredentials(pc);\n pc.restartIce();\n }\n});\n```\n\n### Exposing TURN key secret client-side\n\n```typescript\n// ❌ BAD: Secret exposed to client\nconst secret = 'your-turn-key-secret';\nconst response = await fetch(`https://rtc.live.cloudflare.com/v1/turn/...`, {\n headers: { 'Authorization': `Bearer ${secret}` }\n});\n\n// ✅ GOOD: Generate credentials server-side\nconst response = await fetch('/api/turn-credentials');\n```\n\n## ICE Restart Required Scenarios\n\nThese events require ICE restart (see [patterns.md](./patterns.md#ice-restart-pattern)):\n\n1. **TURN server maintenance** (occasional on Cloudflare's network)\n2. **Network topology changes** (anycast routing changes)\n3. **Credential refresh** during long sessions (>1 hour)\n4. **Connection failure** (iceConnectionState === 'failed')\n\nImplement in all production apps:\n\n```typescript\npc.addEventListener('iceconnectionstatechange', async () => {\n if (pc.iceConnectionState === 'failed' || \n pc.iceConnectionState === 'disconnected') {\n await refreshTURNCredentials(pc);\n pc.restartIce();\n const offer = await pc.createOffer({ iceRestart: true });\n await pc.setLocalDescription(offer);\n // Send offer to peer via signaling...\n }\n});\n```\n\nReference: [RFC 8445 Section 2.4](https://datatracker.ietf.org/doc/html/rfc8445#section-2.4)\n\n## Security Checklist\n\n- [ ] Credentials generated server-side only (never client-side)\n- [ ] TURN_KEY_SECRET in wrangler secrets, not vars\n- [ ] TTL ≤ expected session duration (and ≤ 48 hours)\n- [ ] Rate limiting on credential generation endpoint\n- [ ] Client authentication before issuing credentials\n- [ ] Credential revocation API for compromised sessions\n- [ ] No hardcoded IPs (or DNS monitoring in place)\n- [ ] Port 53 filtered for browser clients\n\n## Troubleshooting\n\n### Issue: TURN credentials not working\n\n**Check:**\n- Key ID and secret are correct\n- Credentials haven't expired (check TTL)\n- TTL doesn't exceed 172800 seconds (48 hours)\n- Server can reach rtc.live.cloudflare.com\n- Network allows outbound HTTPS\n\n**Solution:**\n```typescript\n// Validate before using\nif (ttl > 172800) {\n throw new Error('TTL cannot exceed 48 hours');\n}\n```\n\n### Issue: Slow connection establishment\n\n**Solutions:**\n- Ensure proper ICE candidate gathering\n- Check network latency to Cloudflare edge\n- Verify firewall allows WebRTC ports (3478, 5349, 443)\n- Consider using TURN over TLS (port 443) for corporate networks\n\n### Issue: High packet loss\n\n**Check:**\n- Not exceeding rate limits (5-10k pps)\n- Not exceeding bandwidth limits (50-100 Mbps)\n- Not connecting to too many unique IPs (>5/sec)\n- Client network quality\n\n### Issue: Connection drops after ~48 hours\n\n**Cause**: Credentials expired (48hr max)\n\n**Solution**: \n- Set TTL to expected session duration\n- Implement credential refresh with setConfiguration()\n- Use ICE restart if connection fails\n\n```typescript\n// Refresh credentials before expiry\nconst refreshInterval = ttl * 1000 - 60000; // 1 min early\nsetInterval(async () => {\n await refreshTURNCredentials(pc);\n}, refreshInterval);\n```\n\n### Issue: Port 53 URLs in browser fail silently\n\n**Cause**: Chrome/Firefox block port 53\n\n**Solution**: Filter port 53 URLs server-side:\n\n```typescript\nconst filtered = urls.filter(url => !url.includes(':53'));\n```\n\n### Issue: Hardcoded IPs stop working\n\n**Cause**: Cloudflare changed IP addresses (14-day notice)\n\n**Solution**: \n- Use DNS hostnames (`turn.cloudflare.com`)\n- Monitor DNS changes with automated alerts\n- Update allowlists within 14 days if using IP allowlisting\n\n## Cost Optimization\n\n1. Use appropriate TTLs (don't over-provision)\n2. Implement credential caching\n3. Set `iceTransportPolicy: 'all'` to try direct first (use `'relay'` only when necessary)\n4. Monitor bandwidth usage\n5. Free when used with Cloudflare Calls SFU\n\n## See Also\n\n- [api.md](./api.md) - Credential generation API, revocation\n- [configuration.md](./configuration.md) - IP allowlisting, monitoring\n- [patterns.md](./patterns.md) - ICE restart, credential refresh patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turn/patterns.md", "content": "# TURN Implementation Patterns\n\nProduction-ready patterns for implementing Cloudflare TURN in WebRTC applications.\n\n## Prerequisites\n\nBefore implementing these patterns, ensure you have:\n- TURN key created: see [api.md#create-turn-key](./api.md#create-turn-key)\n- Worker configured: see [configuration.md#cloudflare-worker-integration](./configuration.md#cloudflare-worker-integration)\n\n## Basic TURN Configuration (Browser)\n\n```typescript\ninterface RTCIceServer {\n urls: string | string[];\n username?: string;\n credential?: string;\n credentialType?: \"password\" | \"oauth\";\n}\n\nasync function getTURNConfig(): Promise {\n const response = await fetch('/api/turn-credentials');\n const data = await response.json();\n \n return [\n {\n urls: 'stun:stun.cloudflare.com:3478'\n },\n {\n urls: [\n 'turn:turn.cloudflare.com:3478?transport=udp',\n 'turn:turn.cloudflare.com:3478?transport=tcp',\n 'turns:turn.cloudflare.com:5349?transport=tcp',\n 'turns:turn.cloudflare.com:443?transport=tcp'\n ],\n username: data.username,\n credential: data.credential,\n credentialType: 'password'\n }\n ];\n}\n\n// Use in RTCPeerConnection\nconst iceServers = await getTURNConfig();\nconst peerConnection = new RTCPeerConnection({ iceServers });\n```\n\n## Port Selection Strategy\n\nRecommended order for browser clients:\n\n1. **3478/udp** (primary, lowest latency)\n2. **3478/tcp** (fallback for UDP-blocked networks)\n3. **5349/tls** (corporate firewalls, most reliable)\n4. **443/tls** (alternate TLS port, firewall-friendly)\n\n**Avoid port 53**—blocked by Chrome and Firefox.\n\n```typescript\nfunction filterICEServersForBrowser(urls: string[]): string[] {\n return urls\n .filter(url => !url.includes(':53')) // Remove port 53\n .sort((a, b) => {\n // Prioritize UDP over TCP over TLS\n if (a.includes('transport=udp')) return -1;\n if (b.includes('transport=udp')) return 1;\n if (a.includes('transport=tcp') && !a.startsWith('turns:')) return -1;\n if (b.includes('transport=tcp') && !b.startsWith('turns:')) return 1;\n return 0;\n });\n}\n```\n\n## Credential Refresh (Mid-Session)\n\nWhen credentials expire during long calls:\n\n```typescript\nasync function refreshTURNCredentials(pc: RTCPeerConnection): Promise {\n const newCreds = await fetch('/turn-credentials').then(r => r.json());\n const config = pc.getConfiguration();\n config.iceServers = newCreds.iceServers;\n pc.setConfiguration(config);\n // Note: setConfiguration() does NOT trigger ICE restart\n // Combine with restartIce() if connection fails\n}\n\n// Auto-refresh before expiry\nsetInterval(async () => {\n await refreshTURNCredentials(peerConnection);\n}, 3000000); // 50 minutes if TTL is 1 hour\n```\n\n## ICE Restart Pattern\n\nAfter network change, TURN server maintenance, or credential expiry:\n\n```typescript\npc.addEventListener('iceconnectionstatechange', async () => {\n if (pc.iceConnectionState === 'failed') {\n console.warn('ICE connection failed, restarting...');\n \n // Refresh credentials\n await refreshTURNCredentials(pc);\n \n // Trigger ICE restart\n pc.restartIce();\n const offer = await pc.createOffer({ iceRestart: true });\n await pc.setLocalDescription(offer);\n \n // Send offer to peer via signaling channel...\n }\n});\n```\n\n## Credentials Caching Pattern\n\n```typescript\nclass TURNCredentialsManager {\n private creds: { username: string; credential: string; urls: string[]; expiresAt: number; } | null = null;\n\n async getCredentials(keyId: string, keySecret: string): Promise {\n const now = Date.now();\n \n if (this.creds && this.creds.expiresAt > now) {\n return this.buildIceServers(this.creds);\n }\n\n const ttl = 3600;\n if (ttl > 172800) throw new Error('TTL max 48hrs');\n\n const res = await fetch(\n `https://rtc.live.cloudflare.com/v1/turn/keys/${keyId}/credentials/generate`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${keySecret}`, 'Content-Type': 'application/json' },\n body: JSON.stringify({ ttl })\n }\n );\n\n const data = await res.json();\n const filteredUrls = data.iceServers.urls.filter((url: string) => !url.includes(':53'));\n\n this.creds = {\n username: data.iceServers.username,\n credential: data.iceServers.credential,\n urls: filteredUrls,\n expiresAt: now + (ttl * 1000) - 60000\n };\n\n return this.buildIceServers(this.creds);\n }\n\n private buildIceServers(c: { username: string; credential: string; urls: string[] }): RTCIceServer[] {\n return [\n { urls: 'stun:stun.cloudflare.com:3478' },\n { urls: c.urls, username: c.username, credential: c.credential, credentialType: 'password' as const }\n ];\n }\n}\n```\n\n## Common Use Cases\n\n```typescript\n// Video conferencing: TURN as fallback\nconst config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'all' };\n\n// IoT/predictable connectivity: force TURN\nconst config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'relay' };\n\n// Screen sharing: reduce overhead\nconst pc = new RTCPeerConnection({ iceServers: await getTURNConfig(), bundlePolicy: 'max-bundle' });\n```\n\n## Integration with Cloudflare Calls SFU\n\n```typescript\n// TURN is automatically used when needed\n// Cloudflare Calls handles TURN + SFU coordination\nconst session = await callsClient.createSession({\n appId: 'your-app-id',\n sessionId: 'meeting-123'\n});\n```\n\n## Debugging ICE Connectivity\n\n```typescript\npc.addEventListener('icecandidate', (event) => {\n if (event.candidate) {\n console.log('ICE candidate:', event.candidate.type, event.candidate.protocol);\n }\n});\n\npc.addEventListener('iceconnectionstatechange', () => {\n console.log('ICE state:', pc.iceConnectionState);\n});\n\n// Check selected candidate pair\nconst stats = await pc.getStats();\nstats.forEach(report => {\n if (report.type === 'candidate-pair' && report.selected) {\n console.log('Selected:', report);\n }\n});\n```\n\n## See Also\n\n- [api.md](./api.md) - Credential generation API, types\n- [configuration.md](./configuration.md) - Worker setup, environment variables\n- [gotchas.md](./gotchas.md) - Common mistakes, troubleshooting\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turnstile/README.md", "content": "# Cloudflare Turnstile Implementation Skill Reference\n\nExpert guidance for implementing Cloudflare Turnstile - a smart CAPTCHA alternative that protects websites from bots without showing traditional CAPTCHA puzzles.\n\n## Overview\n\nTurnstile is a user-friendly CAPTCHA alternative that runs challenges in the background without user interaction. It validates visitors automatically using signals like browser behavior, device fingerprinting, and machine learning.\n\n## Widget Types\n\n| Type | Interaction | Use Case |\n|------|-------------|----------|\n| **Managed** (default) | Shows checkbox when needed | Forms, logins - balance UX and security |\n| **Non-Interactive** | Invisible, runs automatically | Frictionless UX, low-risk actions |\n| **Invisible** | Hidden, triggered programmatically | Pre-clearance, API calls, headless |\n\n## Quick Start\n\n### Implicit Rendering (HTML-based)\n```html\n\n\n\n\n
\n
\n \n
\n```\n\n### Explicit Rendering (JavaScript-based)\n```html\n
\n\n\n```\n\n### Server Validation (Required)\n```javascript\n// Cloudflare Workers\nexport default {\n async fetch(request) {\n const formData = await request.formData();\n const token = formData.get('cf-turnstile-response');\n \n const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n secret: env.TURNSTILE_SECRET,\n response: token,\n remoteip: request.headers.get('CF-Connecting-IP')\n })\n });\n \n const validation = await result.json();\n if (!validation.success) {\n return new Response('Invalid CAPTCHA', { status: 400 });\n }\n // Process form...\n }\n}\n```\n\n## Testing Keys\n\n**Critical for development/testing:**\n\n| Type | Key | Behavior |\n|------|-----|----------|\n| **Site Key (Always Passes)** | `1x00000000000000000000AA` | Widget succeeds, token validates |\n| **Site Key (Always Blocks)** | `2x00000000000000000000AB` | Widget fails visibly |\n| **Site Key (Force Challenge)** | `3x00000000000000000000FF` | Always shows interactive challenge |\n| **Secret Key (Testing)** | `1x0000000000000000000000000000000AA` | Validates test tokens |\n\n**Note:** Test keys work on `localhost` and any domain. Do NOT use in production.\n\n## Key Constraints\n\n- **Token expiry:** 5 minutes after generation\n- **Single-use:** Each token can only be validated once\n- **Server validation required:** Client-side checks are insufficient\n\n## Reading Order\n\n1. **[configuration.md](configuration.md)** - Setup, widget options, script loading\n2. **[api.md](api.md)** - JavaScript API, siteverify endpoints, TypeScript types\n3. **[patterns.md](patterns.md)** - Form integration, framework examples, validation patterns\n4. **[gotchas.md](gotchas.md)** - Common errors, debugging, limitations\n\n## See Also\n\n- [Cloudflare Turnstile Docs](https://developers.cloudflare.com/turnstile/)\n- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turnstile/api.md", "content": "# API Reference\n\n## Client-Side JavaScript API\n\nThe Turnstile JavaScript API is available at `window.turnstile` after loading the script.\n\n### `turnstile.render(container, options)`\n\nRenders a Turnstile widget into a container element.\n\n**Parameters:**\n- `container` (string | HTMLElement): CSS selector or DOM element\n- `options` (TurnstileOptions): Configuration object (see [configuration.md](configuration.md))\n\n**Returns:** `string` - Widget ID for use with other API methods\n\n**Example:**\n```javascript\nconst widgetId = window.turnstile.render('#my-container', {\n sitekey: 'YOUR_SITE_KEY',\n callback: (token) => console.log('Success:', token),\n 'error-callback': (code) => console.error('Error:', code)\n});\n```\n\n### `turnstile.reset(widgetId)`\n\nResets a widget (clears token, resets challenge state). Useful when form validation fails.\n\n**Parameters:**\n- `widgetId` (string): Widget ID from `render()`, or container element\n\n**Returns:** `void`\n\n**Example:**\n```javascript\n// Reset on form error\nif (!validateForm()) {\n window.turnstile.reset(widgetId);\n}\n```\n\n### `turnstile.remove(widgetId)`\n\nRemoves a widget from the DOM completely.\n\n**Parameters:**\n- `widgetId` (string): Widget ID from `render()`\n\n**Returns:** `void`\n\n**Example:**\n```javascript\n// Cleanup on navigation\nwindow.turnstile.remove(widgetId);\n```\n\n### `turnstile.getResponse(widgetId)`\n\nGets the current token from a widget (if challenge completed).\n\n**Parameters:**\n- `widgetId` (string): Widget ID from `render()`, or container element\n\n**Returns:** `string | undefined` - Token string, or undefined if not ready\n\n**Example:**\n```javascript\nconst token = window.turnstile.getResponse(widgetId);\nif (token) {\n submitForm(token);\n}\n```\n\n### `turnstile.isExpired(widgetId)`\n\nChecks if a widget's token has expired (>5 minutes old).\n\n**Parameters:**\n- `widgetId` (string): Widget ID from `render()`\n\n**Returns:** `boolean` - True if expired\n\n**Example:**\n```javascript\nif (window.turnstile.isExpired(widgetId)) {\n window.turnstile.reset(widgetId);\n}\n```\n\n## Callback Signatures\n\n```typescript\ntype TurnstileCallback = (token: string) => void;\ntype ErrorCallback = (errorCode: string) => void;\ntype TimeoutCallback = () => void;\ntype ExpiredCallback = () => void;\ntype BeforeInteractiveCallback = () => void;\ntype AfterInteractiveCallback = () => void;\ntype UnsupportedCallback = () => void;\n```\n\n## Siteverify API (Server-Side)\n\n**Endpoint:** `https://challenges.cloudflare.com/turnstile/v0/siteverify`\n\n### Request\n\n**Method:** POST \n**Content-Type:** `application/json` or `application/x-www-form-urlencoded`\n\n```typescript\ninterface SiteverifyRequest {\n secret: string; // Your secret key (never expose client-side)\n response: string; // Token from cf-turnstile-response\n remoteip?: string; // User's IP (optional but recommended)\n idempotency_key?: string; // Unique key for idempotent validation\n}\n```\n\n**Example:**\n```javascript\n// Cloudflare Workers\nconst result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n secret: env.TURNSTILE_SECRET,\n response: token,\n remoteip: request.headers.get('CF-Connecting-IP')\n })\n});\nconst data = await result.json();\n```\n\n### Response\n\n```typescript\ninterface SiteverifyResponse {\n success: boolean; // Validation result\n challenge_ts?: string; // ISO timestamp of challenge\n hostname?: string; // Hostname where widget was solved\n 'error-codes'?: string[]; // Error codes if success=false\n action?: string; // Action name from widget config\n cdata?: string; // Custom data from widget config\n}\n```\n\n**Example Success:**\n```json\n{\n \"success\": true,\n \"challenge_ts\": \"2024-01-15T10:30:00Z\",\n \"hostname\": \"example.com\",\n \"action\": \"login\",\n \"cdata\": \"user123\"\n}\n```\n\n**Example Failure:**\n```json\n{\n \"success\": false,\n \"error-codes\": [\"timeout-or-duplicate\"]\n}\n```\n\n## Error Codes\n\n| Code | Cause | Solution |\n|------|-------|----------|\n| `missing-input-secret` | Secret key not provided | Include `secret` in request |\n| `invalid-input-secret` | Secret key is wrong | Check secret key in dashboard |\n| `missing-input-response` | Token not provided | Include `response` token |\n| `invalid-input-response` | Token is invalid/malformed | Verify token from widget |\n| `timeout-or-duplicate` | Token expired (>5min) or reused | Generate new token, validate once |\n| `internal-error` | Cloudflare server error | Retry with exponential backoff |\n| `bad-request` | Malformed request | Check JSON/form encoding |\n\n## TypeScript Types\n\n```typescript\ninterface TurnstileOptions {\n sitekey: string;\n action?: string;\n cData?: string;\n callback?: (token: string) => void;\n 'error-callback'?: (errorCode: string) => void;\n 'expired-callback'?: () => void;\n 'timeout-callback'?: () => void;\n 'before-interactive-callback'?: () => void;\n 'after-interactive-callback'?: () => void;\n 'unsupported-callback'?: () => void;\n theme?: 'light' | 'dark' | 'auto';\n size?: 'normal' | 'compact' | 'flexible';\n tabindex?: number;\n 'response-field'?: boolean;\n 'response-field-name'?: string;\n retry?: 'auto' | 'never';\n 'retry-interval'?: number;\n language?: string;\n execution?: 'render' | 'execute';\n appearance?: 'always' | 'execute' | 'interaction-only';\n 'refresh-expired'?: 'auto' | 'manual' | 'never';\n}\n\ninterface Turnstile {\n render(container: string | HTMLElement, options: TurnstileOptions): string;\n reset(widgetId: string): void;\n remove(widgetId: string): void;\n getResponse(widgetId: string): string | undefined;\n isExpired(widgetId: string): boolean;\n execute(container?: string | HTMLElement, options?: TurnstileOptions): void;\n}\n\ndeclare global {\n interface Window {\n turnstile: Turnstile;\n onloadTurnstileCallback?: () => void;\n }\n}\n```\n\n## Script Loading\n\n```html\n\n\n\n\n\n\n\n\n\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/turnstile/configuration.md", "content": "# Configuration\n\n## Script Loading\n\n### Basic (Implicit Rendering)\n```html\n\n```\nAutomatically renders widgets with `class=\"cf-turnstile\"` on page load.\n\n### Explicit Rendering\n```html\n\n```\nManual control over when/where widgets render via `window.turnstile.render()`.\n\n### With Load Callback\n```html\n\n\n```\n\n### Compatibility Mode\n```html\n\n```\nProvides `grecaptcha` API for Google reCAPTCHA drop-in replacement.\n\n## Widget Configuration\n\n### Complete Options Object\n\n```javascript\n{\n // Required\n sitekey: 'YOUR_SITE_KEY', // Widget sitekey from dashboard\n\n // Callbacks\n callback: (token) => {}, // Success - token ready\n 'error-callback': (code) => {}, // Error occurred\n 'expired-callback': () => {}, // Token expired (>5min)\n 'timeout-callback': () => {}, // Challenge timeout\n 'before-interactive-callback': () => {}, // Before showing checkbox\n 'after-interactive-callback': () => {}, // After user interacts\n 'unsupported-callback': () => {}, // Browser doesn't support Turnstile\n\n // Appearance\n theme: 'auto', // 'light' | 'dark' | 'auto'\n size: 'normal', // 'normal' | 'compact' | 'flexible'\n tabindex: 0, // Tab order (accessibility)\n language: 'auto', // ISO 639-1 code or 'auto'\n\n // Behavior\n execution: 'render', // 'render' (auto) | 'execute' (manual)\n appearance: 'always', // 'always' | 'execute' | 'interaction-only'\n retry: 'auto', // 'auto' | 'never'\n 'retry-interval': 8000, // Retry interval (ms), default 8000\n 'refresh-expired': 'auto', // 'auto' | 'manual' | 'never'\n\n // Form Integration\n 'response-field': true, // Add hidden input (default: true)\n 'response-field-name': 'cf-turnstile-response', // Hidden input name\n\n // Analytics & Data\n action: 'login', // Action name (for analytics)\n cData: 'user-session-123', // Custom data (returned in siteverify)\n}\n```\n\n### Key Options Explained\n\n**`execution`:**\n- `'render'` (default): Challenge starts immediately on render\n- `'execute'`: Wait for `turnstile.execute()` call\n\n**`appearance`:**\n- `'always'` (default): Widget always visible\n- `'execute'`: Hidden until `execute()` called\n- `'interaction-only'`: Hidden until user interaction needed\n\n**`refresh-expired`:**\n- `'auto'` (default): Auto-refresh expired tokens\n- `'manual'`: App must call `reset()` after expiry\n- `'never'`: No refresh, expired-callback triggered\n\n**`retry`:**\n- `'auto'` (default): Auto-retry failed challenges\n- `'never'`: Don't retry, trigger error-callback\n\n## HTML Data Attributes\n\nFor implicit rendering, use data attributes on `
`:\n\n| JavaScript Property | HTML Data Attribute | Example |\n|---------------------|---------------------|---------|\n| `sitekey` | `data-sitekey` | `data-sitekey=\"YOUR_KEY\"` |\n| `action` | `data-action` | `data-action=\"login\"` |\n| `cData` | `data-cdata` | `data-cdata=\"session-123\"` |\n| `callback` | `data-callback` | `data-callback=\"onSuccess\"` |\n| `error-callback` | `data-error-callback` | `data-error-callback=\"onError\"` |\n| `expired-callback` | `data-expired-callback` | `data-expired-callback=\"onExpired\"` |\n| `timeout-callback` | `data-timeout-callback` | `data-timeout-callback=\"onTimeout\"` |\n| `theme` | `data-theme` | `data-theme=\"dark\"` |\n| `size` | `data-size` | `data-size=\"compact\"` |\n| `tabindex` | `data-tabindex` | `data-tabindex=\"0\"` |\n| `response-field` | `data-response-field` | `data-response-field=\"false\"` |\n| `response-field-name` | `data-response-field-name` | `data-response-field-name=\"token\"` |\n| `retry` | `data-retry` | `data-retry=\"never\"` |\n| `retry-interval` | `data-retry-interval` | `data-retry-interval=\"5000\"` |\n| `language` | `data-language` | `data-language=\"en\"` |\n| `execution` | `data-execution` | `data-execution=\"execute\"` |\n| `appearance` | `data-appearance` | `data-appearance=\"interaction-only\"` |\n| `refresh-expired` | `data-refresh-expired` | `data-refresh-expired=\"manual\"` |\n\n**Example:**\n```html\n
\n```\n\n## Content Security Policy\n\nAdd these directives to CSP header/meta tag:\n\n```\nscript-src https://challenges.cloudflare.com;\nframe-src https://challenges.cloudflare.com;\n```\n\n**Full Example:**\n```html\n\n```\n\n## Framework-Specific Setup\n\n### React\n```bash\nnpm install @marsidev/react-turnstile\n```\n```jsx\nimport Turnstile from '@marsidev/react-turnstile';\n\n console.log(token)}\n/>\n```\n\n### Vue\n```bash\nnpm install vue-turnstile\n```\n```vue\n\n\n```\n\n### Svelte\n```bash\nnpm install svelte-turnstile\n```\n```svelte\n\n\n```\n\n### Next.js (App Router)\n```tsx\n// app/components/TurnstileWidget.tsx\n'use client';\nimport { useEffect, useRef } from 'react';\n\nexport default function TurnstileWidget({ sitekey, onSuccess }) {\n const ref = useRef(null);\n \n useEffect(() => {\n if (ref.current && window.turnstile) {\n const widgetId = window.turnstile.render(ref.current, {\n sitekey,\n callback: onSuccess\n });\n return () => window.turnstile.remove(widgetId);\n }\n }, [sitekey, onSuccess]);\n \n return
;\n}\n```\n\n## Cloudflare Pages Plugin\n\n```bash\nnpm install @cloudflare/pages-plugin-turnstile\n```\n\n```typescript\n// functions/_middleware.ts\nimport turnstilePlugin from '@cloudflare/pages-plugin-turnstile';\n\nexport const onRequest = turnstilePlugin({\n secret: 'YOUR_SECRET_KEY',\n onError: () => new Response('CAPTCHA failed', { status: 403 })\n});\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/turnstile/gotchas.md", "content": "# Troubleshooting & Gotchas\n\n## Critical Rules\n\n### ❌ Skipping Server-Side Validation\n**Problem:** Client-only validation is easily bypassed.\n\n**Solution:** Always validate on server.\n```javascript\n// CORRECT - Server validates token\napp.post('/submit', async (req, res) => {\n const token = req.body['cf-turnstile-response'];\n const validation = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {\n method: 'POST',\n body: JSON.stringify({ secret: SECRET, response: token })\n }).then(r => r.json());\n \n if (!validation.success) return res.status(403).json({ error: 'CAPTCHA failed' });\n});\n```\n\n### ❌ Exposing Secret Key\n**Problem:** Secret key leaked in client-side code.\n\n**Solution:** Server-side validation only. Never send secret to client.\n\n### ❌ Reusing Tokens (Single-Use Rule)\n**Problem:** Tokens are single-use. Revalidation fails with `timeout-or-duplicate`.\n\n**Solution:** Generate new token for each submission. Reset widget on error.\n```javascript\nif (!response.ok) window.turnstile.reset(widgetId);\n```\n\n### ❌ Not Handling Token Expiry\n**Problem:** Tokens expire after 5 minutes.\n\n**Solution:** Handle expiry callback or use auto-refresh.\n```javascript\nwindow.turnstile.render('#container', {\n sitekey: 'YOUR_SITE_KEY',\n 'refresh-expired': 'auto', // or 'manual' with expired-callback\n 'expired-callback': () => window.turnstile.reset(widgetId)\n});\n```\n\n## Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| **Widget not rendering** | Incorrect sitekey, CSP blocking, file:// protocol | Check sitekey, add CSP for challenges.cloudflare.com, use http:// |\n| **timeout-or-duplicate** | Token expired (>5min) or reused | Generate fresh token, don't cache >5min |\n| **invalid-input-secret** | Wrong secret key | Verify secret from dashboard, check env vars |\n| **missing-input-response** | Token not sent | Check form field name is 'cf-turnstile-response' |\n\n## Framework Gotchas\n\n### React: Widget Re-mounting\n**Problem:** Widget re-renders on state change, losing token.\n\n**Solution:** Control lifecycle with useRef.\n```tsx\nfunction TurnstileWidget({ onToken }) {\n const containerRef = useRef(null);\n const widgetIdRef = useRef(null);\n \n useEffect(() => {\n if (containerRef.current && !widgetIdRef.current) {\n widgetIdRef.current = window.turnstile.render(containerRef.current, {\n sitekey: 'YOUR_SITE_KEY',\n callback: onToken\n });\n }\n return () => {\n if (widgetIdRef.current) {\n window.turnstile.remove(widgetIdRef.current);\n widgetIdRef.current = null;\n }\n };\n }, []);\n \n return
;\n}\n```\n\n### React StrictMode: Double Render\n**Problem:** Widget renders twice in dev due to StrictMode.\n\n**Solution:** Use cleanup function.\n```tsx\nuseEffect(() => {\n const widgetId = window.turnstile.render('#container', { sitekey });\n return () => window.turnstile.remove(widgetId);\n}, []);\n```\n\n### Next.js: SSR Hydration\n**Problem:** `window.turnstile` undefined during SSR.\n\n**Solution:** Use `'use client'` or dynamic import with `ssr: false`.\n```tsx\n'use client';\nexport default function Turnstile() { /* component */ }\n```\n\n### SPA: Navigation Without Cleanup\n**Problem:** Navigating leaves orphaned widgets.\n\n**Solution:** Remove widget in cleanup.\n```javascript\n// Vue\nonBeforeUnmount(() => window.turnstile.remove(widgetId));\n\n// React\nuseEffect(() => () => window.turnstile.remove(widgetId), []);\n```\n\n## Network & Security\n\n### CSP Blocking\n**Problem:** Content Security Policy blocks script/iframe.\n\n**Solution:** Add CSP directives.\n```html\n\n```\n\n### IP Address Forwarding\n**Problem:** Server receives proxy IP instead of client IP.\n\n**Solution:** Use correct header.\n```javascript\n// Cloudflare Workers\nconst ip = request.headers.get('CF-Connecting-IP');\n\n// Behind proxy\nconst ip = request.headers.get('X-Forwarded-For')?.split(',')[0];\n```\n\n### CORS (Siteverify)\n**Problem:** CORS error calling siteverify from browser.\n\n**Solution:** Never call siteverify client-side. Call your backend, backend calls siteverify.\n\n## Limits & Constraints\n\n| Limit | Value | Impact |\n|-------|-------|--------|\n| Token validity | 5 minutes | Must regenerate after expiry |\n| Token use | Single-use | Cannot revalidate same token |\n| Widget size | 300x65px (normal), 130x120px (compact) | Plan layout |\n\n## Debugging\n\n### Console Logging\n```javascript\nwindow.turnstile.render('#container', {\n sitekey: 'YOUR_SITE_KEY',\n callback: (token) => console.log('✓ Token:', token),\n 'error-callback': (code) => console.error('✗ Error:', code),\n 'expired-callback': () => console.warn('⏱ Expired'),\n 'timeout-callback': () => console.warn('⏱ Timeout')\n});\n```\n\n### Check Token State\n```javascript\nconst token = window.turnstile.getResponse(widgetId);\nconsole.log('Token:', token || 'NOT READY');\nconsole.log('Expired:', window.turnstile.isExpired(widgetId));\n```\n\n### Test Keys (Use First)\nAlways develop with test keys before production:\n- Site: `1x00000000000000000000AA`\n- Secret: `1x0000000000000000000000000000000AA`\n\n### Network Tab\n- Verify `api.js` loads (200 OK)\n- Check siteverify request/response\n- Look for 4xx/5xx errors\n\n## Misconfigurations\n\n### Wrong Key Pairing\n**Problem:** Site key from one widget, secret from another.\n\n**Solution:** Verify site key and secret are from same widget in dashboard.\n\n### Test Keys in Production\n**Problem:** Using test keys in production.\n\n**Solution:** Environment-based keys.\n```javascript\nconst SITE_KEY = process.env.NODE_ENV === 'production'\n ? process.env.TURNSTILE_SITE_KEY\n : '1x00000000000000000000AA';\n```\n\n### Missing Environment Variables\n**Problem:** Secret undefined on server.\n\n**Solution:** Check .env and verify loading.\n```bash\n# .env\nTURNSTILE_SECRET=your_secret_here\n\n# Verify\nconsole.log('Secret loaded:', !!process.env.TURNSTILE_SECRET);\n```\n\n## Reference\n\n- [Turnstile Docs](https://developers.cloudflare.com/turnstile/)\n- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)\n- [Error Codes](https://developers.cloudflare.com/turnstile/troubleshooting/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/turnstile/patterns.md", "content": "# Common Patterns\n\n## Form Integration\n\n### Basic Form (Implicit Rendering)\n\n```html\n\n\n\n \n\n\n
\n \n
\n \n
\n\n\n```\n\n### Controlled Form (Explicit Rendering)\n\n```javascript\n\n\n```\n\n## Framework Patterns\n\n### React\n\n```tsx\nimport { useState } from 'react';\nimport Turnstile from '@marsidev/react-turnstile';\n\nexport default function Form() {\n const [token, setToken] = useState(null);\n\n return (\n
{\n e.preventDefault();\n if (!token) return;\n await fetch('/api/submit', { \n method: 'POST',\n body: JSON.stringify({ 'cf-turnstile-response': token })\n });\n }}>\n \n \n \n );\n}\n```\n\n### Vue / Svelte\n\n```vue\n\n\n\n\n token = e.detail.token} />\n```\n\n## Server Validation\n\n### Cloudflare Workers\n\n```typescript\ninterface Env {\n TURNSTILE_SECRET: string;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n if (request.method !== 'POST') {\n return new Response('Method not allowed', { status: 405 });\n }\n \n const formData = await request.formData();\n const token = formData.get('cf-turnstile-response');\n \n if (!token) {\n return new Response('Missing token', { status: 400 });\n }\n \n // Validate token\n const ip = request.headers.get('CF-Connecting-IP');\n const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n secret: env.TURNSTILE_SECRET,\n response: token,\n remoteip: ip\n })\n });\n \n const validation = await result.json();\n \n if (!validation.success) {\n return new Response('CAPTCHA validation failed', { status: 403 });\n }\n \n // Process form...\n return new Response('Success');\n }\n};\n```\n\n### Pages Functions\n\n```typescript\n// functions/submit.ts - same pattern as Workers, use ctx.env and ctx.request\nexport const onRequestPost: PagesFunction<{ TURNSTILE_SECRET: string }> = async (ctx) => {\n const token = (await ctx.request.formData()).get('cf-turnstile-response');\n // Validate with ctx.env.TURNSTILE_SECRET (same as Workers pattern above)\n};\n```\n\n## Advanced Patterns\n\n### Pre-Clearance (Invisible)\n\n```html\n
\n
\n \n
\n\n\n\n```\n\n### Token Refresh on Expiry\n\n```javascript\nlet widgetId = window.turnstile.render('#container', {\n sitekey: 'YOUR_SITE_KEY',\n 'refresh-expired': 'manual',\n 'expired-callback': () => {\n console.log('Token expired, refreshing...');\n window.turnstile.reset(widgetId);\n }\n});\n```\n\n## Testing\n\n### Environment-Based Keys\n\n```javascript\nconst SITE_KEY = process.env.NODE_ENV === 'production'\n ? 'YOUR_PRODUCTION_SITE_KEY'\n : '1x00000000000000000000AA'; // Always passes\n\nconst SECRET_KEY = process.env.NODE_ENV === 'production'\n ? process.env.TURNSTILE_SECRET\n : '1x0000000000000000000000000000000AA';\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/vectorize/README.md", "content": "# Cloudflare Vectorize\n\nGlobally distributed vector database for AI applications. Store and query vector embeddings for semantic search, recommendations, RAG, and classification.\n\n**Status:** Generally Available (GA) | **Last Updated:** 2026-01-27\n\n## Quick Start\n\n```typescript\n// 1. Create index\n// npx wrangler vectorize create my-index --dimensions=768 --metric=cosine\n\n// 2. Configure binding (wrangler.jsonc)\n// { \"vectorize\": [{ \"binding\": \"VECTORIZE\", \"index_name\": \"my-index\" }] }\n\n// 3. Query vectors\nconst matches = await env.VECTORIZE.query(queryVector, { topK: 5 });\n```\n\n## Key Features\n\n- **10M vectors per index** (V2)\n- Dimensions up to 1536 (32-bit float)\n- Three distance metrics: cosine, euclidean, dot-product\n- Metadata filtering (up to 10 indexes)\n- Namespace support (50K namespaces paid, 1K free)\n- Seamless Workers AI integration\n- Global distribution\n\n## Reading Order\n\n| Task | Files to Read |\n|------|---------------|\n| New to Vectorize | README only |\n| Implement feature | README + api + patterns |\n| Setup/configure | README + configuration |\n| Debug issues | gotchas |\n| Integrate with AI | README + patterns |\n| RAG implementation | README + patterns |\n\n## File Guide\n\n- **README.md** (this file): Overview, quick decisions\n- **api.md**: Runtime API, types, operations (query/insert/upsert)\n- **configuration.md**: Setup, CLI, metadata indexes\n- **patterns.md**: RAG, Workers AI, OpenAI, LangChain, multi-tenant\n- **gotchas.md**: Limits, pitfalls, troubleshooting\n\n## Distance Metric Selection\n\nChoose based on your use case:\n\n```\nWhat are you building?\n├─ Text/semantic search → cosine (most common)\n├─ Image similarity → euclidean\n├─ Recommendation system → dot-product\n└─ Pre-normalized vectors → dot-product\n```\n\n| Metric | Best For | Score Interpretation |\n|--------|----------|---------------------|\n| `cosine` | Text embeddings, semantic similarity | Higher = closer (1.0 = identical) |\n| `euclidean` | Absolute distance, spatial data | Lower = closer (0.0 = identical) |\n| `dot-product` | Recommendations, normalized vectors | Higher = closer |\n\n**Note:** Index configuration is immutable. Cannot change dimensions or metric after creation.\n\n## Multi-Tenancy Strategy\n\n```\nHow many tenants?\n├─ < 50K tenants → Use namespaces (recommended)\n│ ├─ Fastest (filter before vector search)\n│ └─ Strict isolation\n├─ > 50K tenants → Use metadata filtering\n│ ├─ Slower (post-filter after vector search)\n│ └─ Requires metadata index\n└─ Per-tenant indexes → Only if compliance mandated\n └─ 50K index limit per account (paid plan)\n```\n\n## Common Workflows\n\n### Semantic Search\n\n```typescript\n// 1. Generate embedding\nconst result = await env.AI.run(\"@cf/baai/bge-base-en-v1.5\", { text: [query] });\n\n// 2. Query Vectorize\nconst matches = await env.VECTORIZE.query(result.data[0], {\n topK: 5,\n returnMetadata: \"indexed\"\n});\n```\n\n### RAG Pattern\n\n```typescript\n// 1. Generate query embedding\nconst embedding = await env.AI.run(\"@cf/baai/bge-base-en-v1.5\", { text: [query] });\n\n// 2. Search Vectorize\nconst matches = await env.VECTORIZE.query(embedding.data[0], { topK: 5 });\n\n// 3. Fetch full documents from R2/D1/KV\nconst docs = await Promise.all(matches.matches.map(m => \n env.R2.get(m.metadata.key).then(obj => obj?.text())\n));\n\n// 4. Generate LLM response with context\nconst answer = await env.AI.run(\"@cf/meta/llama-3-8b-instruct\", {\n prompt: `Context: ${docs.join(\"\\n\\n\")}\\n\\nQuestion: ${query}\\n\\nAnswer:`\n});\n```\n\n## Critical Gotchas\n\nSee `gotchas.md` for details. Most important:\n\n1. **Async mutations**: Inserts take 5-10s to be queryable\n2. **500 batch limit**: Workers API enforces 500 vectors per call (undocumented)\n3. **Metadata truncation**: `\"indexed\"` returns first 64 bytes only\n4. **topK with metadata**: Max 20 (not 100) when using returnValues or returnMetadata: \"all\"\n5. **Metadata indexes first**: Must create before inserting vectors\n\n## Resources\n\n- [Official Docs](https://developers.cloudflare.com/vectorize/)\n- [Client API Reference](https://developers.cloudflare.com/vectorize/reference/client-api/)\n- [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/#text-embeddings)\n- [Discord: #vectorize](https://discord.cloudflare.com)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/vectorize/api.md", "content": "# Vectorize API Reference\n\n## Types\n\n```typescript\ninterface VectorizeVector {\n id: string; // Max 64 bytes\n values: number[]; // Must match index dimensions\n namespace?: string; // Optional partition (max 64 bytes)\n metadata?: Record; // Max 10 KiB\n}\n```\n\n## Query\n\n```typescript\nconst matches = await env.VECTORIZE.query(queryVector, {\n topK: 10, // Max 100 (or 20 with returnValues/returnMetadata:\"all\")\n returnMetadata: \"indexed\", // \"none\" | \"indexed\" | \"all\"\n returnValues: false,\n namespace: \"tenant-123\",\n filter: { category: \"docs\" }\n});\n// matches.matches[0] = { id, score, metadata? }\n```\n\n**returnMetadata:** `\"none\"` (fastest) → `\"indexed\"` (recommended) → `\"all\"` (topK max 20)\n\n**queryById (V2 only):** Search using existing vector as query.\n```typescript\nawait env.VECTORIZE.queryById(\"doc-123\", { topK: 5 });\n```\n\n## Insert/Upsert\n\n```typescript\n// Insert: ignores duplicates (keeps first)\nawait env.VECTORIZE.insert([{ id, values, metadata }]);\n\n// Upsert: overwrites duplicates (keeps last)\nawait env.VECTORIZE.upsert([{ id, values, metadata }]);\n```\n\n**Max 500 vectors per call.** Queryable after 5-10 seconds.\n\n## Other Operations\n\n```typescript\n// Get by IDs\nconst vectors = await env.VECTORIZE.getByIds([\"id1\", \"id2\"]);\n\n// Delete (max 1000 IDs per call)\nawait env.VECTORIZE.deleteByIds([\"id1\", \"id2\"]);\n\n// Index info\nconst info = await env.VECTORIZE.describe();\n// { dimensions, metric, vectorCount }\n```\n\n## Filtering\n\nRequires metadata index. Filter operators:\n\n| Operator | Example |\n|----------|---------|\n| `$eq` (implicit) | `{ category: \"docs\" }` |\n| `$ne` | `{ status: { $ne: \"deleted\" } }` |\n| `$in` / `$nin` | `{ tag: { $in: [\"sale\"] } }` |\n| `$lt`, `$lte`, `$gt`, `$gte` | `{ price: { $lt: 100 } }` |\n\n**Constraints:** Max 2048 bytes, no dots/`$` in keys, values: string/number/boolean/null.\n\n## Performance\n\n| Configuration | topK Limit | Speed |\n|--------------|------------|-------|\n| No metadata | 100 | Fastest |\n| `returnMetadata: \"indexed\"` | 100 | Fast |\n| `returnMetadata: \"all\"` | 20 | Slower |\n| `returnValues: true` | 20 | Slower |\n\n**Batch operations:** Always batch (500/call) for optimal throughput.\n\n```typescript\nfor (let i = 0; i < vectors.length; i += 500) {\n await env.VECTORIZE.upsert(vectors.slice(i, i + 500));\n}\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/vectorize/configuration.md", "content": "# Vectorize Configuration\n\n## Create Index\n\n```bash\nnpx wrangler vectorize create my-index --dimensions=768 --metric=cosine\n```\n\n**⚠️ Dimensions and metric are immutable** - cannot change after creation.\n\n## Worker Binding\n\n```jsonc\n// wrangler.jsonc\n{\n \"vectorize\": [\n { \"binding\": \"VECTORIZE\", \"index_name\": \"my-index\" }\n ]\n}\n```\n\n```typescript\ninterface Env {\n VECTORIZE: Vectorize;\n}\n```\n\n## Metadata Indexes\n\n**Must create BEFORE inserting vectors** - existing vectors not retroactively indexed.\n\n```bash\nwrangler vectorize create-metadata-index my-index --property-name=category --type=string\nwrangler vectorize create-metadata-index my-index --property-name=price --type=number\n```\n\n| Type | Use For |\n|------|---------|\n| `string` | Categories, tags (first 64 bytes indexed) |\n| `number` | Prices, timestamps |\n| `boolean` | Flags |\n\n## CLI Commands\n\n```bash\n# Index management\nwrangler vectorize list\nwrangler vectorize info \nwrangler vectorize delete \n\n# Vector operations\nwrangler vectorize insert --file=embeddings.ndjson\nwrangler vectorize get --ids=id1,id2\nwrangler vectorize delete-by-ids --ids=id1,id2\n\n# Metadata indexes\nwrangler vectorize list-metadata-index \nwrangler vectorize delete-metadata-index --property-name=field\n```\n\n## Bulk Upload (NDJSON)\n\n```json\n{\"id\": \"1\", \"values\": [0.1, 0.2, ...], \"metadata\": {\"category\": \"docs\"}}\n{\"id\": \"2\", \"values\": [0.4, 0.5, ...], \"namespace\": \"tenant-abc\"}\n```\n\n**Limits:** 5000 vectors per file, 100 MB max\n\n## Cardinality Best Practice\n\nBucket high-cardinality data:\n```typescript\n// ❌ Millisecond timestamps\nmetadata: { timestamp: Date.now() }\n\n// ✅ 5-minute buckets\nmetadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }\n```\n\n## Production Checklist\n\n1. Create index with correct dimensions\n2. Create metadata indexes FIRST\n3. Test bulk upload\n4. Configure bindings\n5. Deploy Worker\n6. Verify queries\n" }, { "path": "skills/.curated/cloudflare-deploy/references/vectorize/gotchas.md", "content": "# Vectorize Gotchas\n\n## Critical Warnings\n\n### Async Mutations\nInsert/upsert/delete return immediately but vectors aren't queryable for 5-10 seconds.\n\n### Batch Size Limit\n**Workers API: 500 vectors max per call** (undocumented, silently truncates)\n\n```typescript\n// ✅ Chunk into 500\nfor (let i = 0; i < vectors.length; i += 500) {\n await env.VECTORIZE.upsert(vectors.slice(i, i + 500));\n}\n```\n\n### Metadata Truncation\n`returnMetadata: \"indexed\"` returns only first 64 bytes of strings. Use `\"all\"` for complete metadata (but max topK drops to 20).\n\n### topK Limits\n\n| returnMetadata | returnValues | Max topK |\n|----------------|--------------|----------|\n| `\"none\"` / `\"indexed\"` | `false` | 100 |\n| `\"all\"` | any | **20** |\n| any | `true` | **20** |\n\n### Metadata Indexes First\nCreate BEFORE inserting - existing vectors not retroactively indexed.\n\n```bash\n# ✅ Create index FIRST\nwrangler vectorize create-metadata-index my-index --property-name=category --type=string\nwrangler vectorize insert my-index --file=data.ndjson\n```\n\n### Index Config Immutable\nCannot change dimensions/metric after creation. Must create new index and migrate.\n\n## Limits (V2)\n\n| Resource | Limit |\n|----------|-------|\n| Vectors per index | 10,000,000 |\n| Max dimensions | 1536 |\n| Batch upsert (Workers) | **500** |\n| Indexed string metadata | **64 bytes** |\n| Metadata indexes | 10 |\n| Namespaces | 50,000 (paid) / 1,000 (free) |\n\n## Common Mistakes\n\n1. **Wrong embedding shape:** Extract `result.data[0]` from Workers AI\n2. **Metadata index after data:** Re-upsert all vectors\n3. **Insert vs upsert:** `insert` ignores duplicates, `upsert` overwrites\n4. **Not batching:** Individual inserts ~1K/min, batched ~200K+/min\n\n## Troubleshooting\n\n**No results?**\n- Wait 5-10s after insert\n- Check namespace spelling (case-sensitive)\n- Verify metadata index exists\n- Check dimension mismatch\n\n**Metadata filter not working?**\n- Index must exist before data insert\n- Strings >64 bytes truncated\n- Use dot notation for nested: `\"product.category\"`\n\n## Model Dimensions\n\n- `@cf/baai/bge-small-en-v1.5`: 384\n- `@cf/baai/bge-base-en-v1.5`: 768\n- `@cf/baai/bge-large-en-v1.5`: 1024\n" }, { "path": "skills/.curated/cloudflare-deploy/references/vectorize/patterns.md", "content": "# Vectorize Patterns\n\n## Workers AI Integration\n\n```typescript\n// Generate embedding + query\nconst result = await env.AI.run(\"@cf/baai/bge-base-en-v1.5\", { text: [query] });\nconst matches = await env.VECTORIZE.query(result.data[0], { topK: 5 }); // Pass data[0]!\n```\n\n| Model | Dimensions |\n|-------|------------|\n| `@cf/baai/bge-small-en-v1.5` | 384 |\n| `@cf/baai/bge-base-en-v1.5` | 768 (recommended) |\n| `@cf/baai/bge-large-en-v1.5` | 1024 |\n\n## OpenAI Integration\n\n```typescript\nconst response = await openai.embeddings.create({ model: \"text-embedding-ada-002\", input: query });\nconst matches = await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 });\n```\n\n## RAG Pattern\n\n```typescript\n// 1. Embed query\nconst emb = await env.AI.run(\"@cf/baai/bge-base-en-v1.5\", { text: [query] });\n\n// 2. Search vectors\nconst matches = await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: \"indexed\" });\n\n// 3. Fetch full docs from R2/D1/KV\nconst docs = await Promise.all(matches.matches.map(m => env.R2.get(m.metadata.key).then(o => o?.text())));\n\n// 4. Generate with context\nconst answer = await env.AI.run(\"@cf/meta/llama-3-8b-instruct\", {\n prompt: `Context:\\n${docs.filter(Boolean).join(\"\\n\\n\")}\\n\\nQuestion: ${query}\\n\\nAnswer:`\n});\n```\n\n## Multi-Tenant\n\n### Namespaces (< 50K tenants, fastest)\n\n```typescript\nawait env.VECTORIZE.upsert([{ id: \"1\", values: emb, namespace: `tenant-${id}` }]);\nawait env.VECTORIZE.query(vec, { namespace: `tenant-${id}`, topK: 10 });\n```\n\n### Metadata Filter (> 50K tenants)\n\n```bash\nwrangler vectorize create-metadata-index my-index --property-name=tenantId --type=string\n```\n\n```typescript\nawait env.VECTORIZE.upsert([{ id: \"1\", values: emb, metadata: { tenantId: id } }]);\nawait env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });\n```\n\n## Hybrid Search\n\n```typescript\nconst matches = await env.VECTORIZE.query(vec, {\n topK: 20,\n filter: {\n category: { $in: [\"tech\", \"science\"] },\n published: { $gte: lastMonthTimestamp }\n }\n});\n```\n\n## Batch Ingestion\n\n```typescript\nconst BATCH = 500;\nfor (let i = 0; i < vectors.length; i += BATCH) {\n await env.VECTORIZE.upsert(vectors.slice(i, i + BATCH));\n}\n```\n\n## Best Practices\n\n1. **Pass `data[0]`** not `data` or full response\n2. **Batch 500** vectors per upsert\n3. **Create metadata indexes** before inserting\n4. **Use namespaces** for tenant isolation (faster than filters)\n5. **`returnMetadata: \"indexed\"`** for best speed/data balance\n6. **Handle 5-10s mutation delay** in async operations\n" }, { "path": "skills/.curated/cloudflare-deploy/references/waf/README.md", "content": "# Cloudflare WAF Expert Skill Reference\n\n**Expertise**: Cloudflare Web Application Firewall (WAF) configuration, custom rules, managed rulesets, rate limiting, attack detection, and API integration\n\n## Overview\n\nCloudflare WAF protects web applications from attacks through managed rulesets and custom rules.\n\n**Detection (Managed Rulesets)**\n- Pre-configured rules maintained by Cloudflare\n- CVE-based rules, OWASP Top 10 coverage\n- Three main rulesets: Cloudflare Managed, OWASP CRS, Exposed Credentials\n- Actions: log, block, challenge, js_challenge, managed_challenge\n\n**Mitigation (Custom Rules & Rate Limiting)**\n- Custom expressions using Wirefilter syntax\n- Attack score-based blocking (`cf.waf.score`)\n- Rate limiting with per-IP, per-user, or custom characteristics\n- Actions: block, challenge, js_challenge, managed_challenge, log, skip\n\n## Quick Start\n\n### Deploy Cloudflare Managed Ruleset\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });\n\n// Deploy managed ruleset to zone\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_managed',\n name: 'Deploy Cloudflare Managed Ruleset',\n rules: [{\n action: 'execute',\n action_parameters: {\n id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed Ruleset\n },\n expression: 'true',\n enabled: true,\n }],\n});\n```\n\n### Create Custom Rule\n```typescript\n// Block requests with attack score >= 40\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_custom',\n name: 'Custom WAF Rules',\n rules: [{\n action: 'block',\n expression: 'cf.waf.score gt 40',\n description: 'Block high attack scores',\n enabled: true,\n }],\n});\n```\n\n### Create Rate Limit\n```typescript\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_ratelimit',\n name: 'API Rate Limits',\n rules: [{\n action: 'block',\n expression: 'http.request.uri.path eq \"/api/login\"',\n action_parameters: {\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src'],\n period: 60,\n requests_per_period: 10,\n mitigation_timeout: 600,\n },\n },\n enabled: true,\n }],\n});\n```\n\n## Managed Ruleset Quick Reference\n\n| Ruleset Name | ID | Coverage |\n|--------------|----|---------| \n| Cloudflare Managed | `efb7b8c949ac4650a09736fc376e9aee` | OWASP Top 10, CVEs |\n| OWASP Core Ruleset | `4814384a9e5d4991b9815dcfc25d2f1f` | OWASP ModSecurity CRS |\n| Exposed Credentials Check | `c2e184081120413c86c3ab7e14069605` | Credential stuffing |\n\n## Phases\n\nWAF rules execute in specific phases:\n- `http_request_firewall_managed` - Managed rulesets\n- `http_request_firewall_custom` - Custom rules\n- `http_ratelimit` - Rate limiting rules\n- `http_request_sbfm` - Super Bot Fight Mode (Pro+)\n\n## Reading Order\n\n1. **[api.md](api.md)** - SDK methods, expressions, actions, parameters\n2. **[configuration.md](configuration.md)** - Setup with Wrangler, Terraform, Pulumi\n3. **[patterns.md](patterns.md)** - Common patterns: deploy managed, rate limiting, skip, override\n4. **[gotchas.md](gotchas.md)** - Execution order, limits, expression errors\n\n## See Also\n\n- [Cloudflare WAF Docs](https://developers.cloudflare.com/waf/)\n- [Ruleset Engine](https://developers.cloudflare.com/ruleset-engine/)\n- [Expression Reference](https://developers.cloudflare.com/ruleset-engine/rules-language/)" }, { "path": "skills/.curated/cloudflare-deploy/references/waf/api.md", "content": "# API Reference\n\n## SDK Setup\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({\n apiToken: process.env.CF_API_TOKEN,\n});\n```\n\n## Core Methods\n\n```typescript\n// List rulesets\nawait client.rulesets.list({ zone_id: 'zone_id', phase: 'http_request_firewall_managed' });\n\n// Get ruleset\nawait client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });\n\n// Create ruleset\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_custom',\n name: 'Custom WAF Rules',\n rules: [{ action: 'block', expression: 'cf.waf.score gt 40', enabled: true }],\n});\n\n// Update ruleset (include rule id to keep existing, omit id for new rules)\nawait client.rulesets.update({\n zone_id: 'zone_id',\n ruleset_id: 'ruleset_id',\n rules: [\n { id: 'rule_id', action: 'block', expression: 'cf.waf.score gt 40', enabled: true },\n { action: 'challenge', expression: 'http.request.uri.path contains \"/admin\"', enabled: true },\n ],\n});\n\n// Delete ruleset\nawait client.rulesets.delete({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });\n```\n\n## Actions & Phases\n\n### Actions by Phase\n\n| Action | Custom | Managed | Rate Limit | Description |\n|--------|--------|---------|------------|-------------|\n| `block` | ✅ | ❌ | ✅ | Block request with 403 |\n| `challenge` | ✅ | ❌ | ✅ | Show CAPTCHA challenge |\n| `js_challenge` | ✅ | ❌ | ✅ | JS-based challenge |\n| `managed_challenge` | ✅ | ❌ | ✅ | Smart challenge (recommended) |\n| `log` | ✅ | ❌ | ✅ | Log only, don't block |\n| `skip` | ✅ | ❌ | ❌ | Skip rule evaluation |\n| `execute` | ❌ | ✅ | ❌ | Deploy managed ruleset |\n\n### Phases (Execution Order)\n\n1. `http_request_firewall_custom` - Custom rules (first line of defense)\n2. `http_request_firewall_managed` - Managed rulesets (pre-configured protection)\n3. `http_ratelimit` - Rate limiting (request throttling)\n4. `http_request_sbfm` - Super Bot Fight Mode (Pro+ only)\n\n## Expression Syntax\n\n### Fields\n\n```typescript\n// Request properties\nhttp.request.method // GET, POST, etc.\nhttp.request.uri.path // /api/users\nhttp.host // example.com\n\n// IP and Geolocation\nip.src // 192.0.2.1\nip.geoip.country // US, GB, etc.\nip.geoip.continent // NA, EU, etc.\n\n// Attack detection\ncf.waf.score // 0-100 attack score\ncf.waf.score.sqli // SQL injection score\ncf.waf.score.xss // XSS score\n\n// Headers & Cookies\nhttp.request.headers[\"authorization\"][0]\nhttp.request.cookies[\"session\"][0]\nlower(http.user_agent) // Lowercase user agent\n```\n\n### Operators\n\n```typescript\n// Comparison\neq // Equal\nne // Not equal\nlt // Less than\nle // Less than or equal\ngt // Greater than\nge // Greater than or equal\n\n// String matching\ncontains // Substring match\nmatches // Regex match (use carefully)\nstarts_with // Prefix match\nends_with // Suffix match\n\n// List operations\nin // Value in list\nnot // Logical NOT\nand // Logical AND\nor // Logical OR\n```\n\n### Expression Examples\n\n```typescript\n'cf.waf.score gt 40' // Attack score\n'http.request.uri.path eq \"/api/login\" and http.request.method eq \"POST\"' // Path + method\n'ip.src in {192.0.2.0/24 203.0.113.0/24}' // IP blocking\n'ip.geoip.country in {\"CN\" \"RU\" \"KP\"}' // Country blocking\n'http.user_agent contains \"bot\"' // User agent\n'not http.request.headers[\"authorization\"][0]' // Header check\n'(cf.waf.score.sqli gt 20 or cf.waf.score.xss gt 20) and http.request.uri.path starts_with \"/api\"' // Complex\n```\n\n## Rate Limiting Configuration\n\n```typescript\n{\n action: 'block',\n expression: 'http.request.uri.path starts_with \"/api\"',\n action_parameters: {\n ratelimit: {\n // Characteristics define uniqueness: 'ip.src', 'cf.colo.id', \n // 'http.request.headers[\"key\"][0]', 'http.request.cookies[\"session\"][0]'\n characteristics: ['cf.colo.id', 'ip.src'], // Recommended: per-IP per-datacenter\n period: 60, // Time window in seconds\n requests_per_period: 100, // Max requests in period\n mitigation_timeout: 600, // Block duration in seconds\n counting_expression: 'http.request.method ne \"GET\"', // Optional: filter counted requests\n requests_to_origin: false, // Count all requests (not just origin hits)\n },\n },\n enabled: true,\n}\n```\n\n## Managed Ruleset Deployment\n\n```typescript\n{\n action: 'execute',\n action_parameters: {\n id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed\n overrides: {\n // Override specific rules\n rules: [\n { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log', enabled: true },\n ],\n // Override categories: 'wordpress', 'sqli', 'xss', 'rce', etc.\n categories: [\n { category: 'wordpress', enabled: false },\n { category: 'sqli', action: 'log' },\n ],\n },\n },\n expression: 'true',\n enabled: true,\n}\n```\n\n## Skip Rules\n\nSkip rules bypass subsequent rule evaluation. Two skip types:\n\n**Skip current ruleset**: Skip remaining rules in current phase only\n```typescript\n{\n action: 'skip',\n action_parameters: {\n ruleset: 'current', // Skip rest of current ruleset\n },\n expression: 'http.request.uri.path ends_with \".jpg\" or http.request.uri.path ends_with \".css\"',\n enabled: true,\n}\n```\n\n**Skip entire phases**: Skip one or more phases completely\n```typescript\n{\n action: 'skip',\n action_parameters: {\n phases: ['http_request_firewall_managed', 'http_ratelimit'], // Skip multiple phases\n },\n expression: 'ip.src in {192.0.2.0/24 203.0.113.0/24}',\n enabled: true,\n}\n```\n\n**Note**: Skip rules in custom phase can skip managed/ratelimit phases, but not vice versa (execution order)." }, { "path": "skills/.curated/cloudflare-deploy/references/waf/configuration.md", "content": "# Configuration\n\n## Prerequisites\n\n**API Token**: Create at https://dash.cloudflare.com/profile/api-tokens\n- Permission: `Zone.WAF Edit` or `Zone.Firewall Services Edit`\n- Zone Resources: Include specific zones or all zones\n\n**Zone ID**: Found in dashboard > Overview > API section (right sidebar)\n\n```bash\n# Set environment variables\nexport CF_API_TOKEN=\"your_api_token_here\"\nexport ZONE_ID=\"your_zone_id_here\"\n```\n\n## TypeScript SDK Usage\n\n```bash\nnpm install cloudflare\n```\n\n```typescript\nimport Cloudflare from 'cloudflare';\n\nconst client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });\n\n// Custom rules\nawait client.rulesets.create({\n zone_id: process.env.ZONE_ID,\n kind: 'zone',\n phase: 'http_request_firewall_custom',\n name: 'Custom WAF',\n rules: [\n { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },\n { action: 'challenge', expression: 'http.request.uri.path eq \"/admin\"', enabled: true },\n ],\n});\n\n// Managed ruleset\nawait client.rulesets.create({\n zone_id: process.env.ZONE_ID,\n phase: 'http_request_firewall_managed',\n rules: [{\n action: 'execute',\n action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee' },\n expression: 'true',\n }],\n});\n\n// Rate limiting\nawait client.rulesets.create({\n zone_id: process.env.ZONE_ID,\n phase: 'http_ratelimit',\n rules: [{\n action: 'block',\n expression: 'http.request.uri.path starts_with \"/api\"',\n action_parameters: {\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src'],\n period: 60,\n requests_per_period: 100,\n mitigation_timeout: 600,\n },\n },\n }],\n});\n```\n\n## Terraform Configuration\n\n```hcl\nprovider \"cloudflare\" {\n api_token = var.cloudflare_api_token\n}\n\nresource \"cloudflare_ruleset\" \"waf_custom\" {\n zone_id = var.zone_id\n kind = \"zone\"\n phase = \"http_request_firewall_custom\"\n\n rules {\n action = \"block\"\n expression = \"cf.waf.score gt 50\"\n }\n}\n```\n\n**Managed Ruleset & Rate Limiting**:\n```hcl\nresource \"cloudflare_ruleset\" \"waf_managed\" {\n zone_id = var.zone_id\n name = \"Managed Ruleset\"\n kind = \"zone\"\n phase = \"http_request_firewall_managed\"\n\n rules {\n action = \"execute\"\n action_parameters {\n id = \"efb7b8c949ac4650a09736fc376e9aee\"\n overrides {\n rules {\n id = \"5de7edfa648c4d6891dc3e7f84534ffa\"\n action = \"log\"\n }\n }\n }\n expression = \"true\"\n }\n}\n\nresource \"cloudflare_ruleset\" \"rate_limiting\" {\n zone_id = var.zone_id\n phase = \"http_ratelimit\"\n\n rules {\n action = \"block\"\n expression = \"http.request.uri.path starts_with \\\"/api\\\"\"\n ratelimit {\n characteristics = [\"cf.colo.id\", \"ip.src\"]\n period = 60\n requests_per_period = 100\n mitigation_timeout = 600\n }\n }\n}\n```\n\n## Pulumi Configuration\n\n```typescript\nimport * as cloudflare from '@pulumi/cloudflare';\n\nconst zoneId = 'zone_id';\n\n// Custom rules\nconst wafCustom = new cloudflare.Ruleset('waf-custom', {\n zoneId,\n phase: 'http_request_firewall_custom',\n rules: [\n { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },\n { action: 'challenge', expression: 'http.request.uri.path eq \"/admin\"', enabled: true },\n ],\n});\n\n// Managed ruleset\nconst wafManaged = new cloudflare.Ruleset('waf-managed', {\n zoneId,\n phase: 'http_request_firewall_managed',\n rules: [{\n action: 'execute',\n actionParameters: { id: 'efb7b8c949ac4650a09736fc376e9aee' },\n expression: 'true',\n }],\n});\n\n// Rate limiting\nconst rateLimiting = new cloudflare.Ruleset('rate-limiting', {\n zoneId,\n phase: 'http_ratelimit',\n rules: [{\n action: 'block',\n expression: 'http.request.uri.path starts_with \"/api\"',\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src'],\n period: 60,\n requestsPerPeriod: 100,\n mitigationTimeout: 600,\n },\n }],\n});\n```\n\n## Dashboard Configuration\n\n1. Navigate to: **Security** > **WAF**\n2. Select tab:\n - **Managed rules** - Deploy/configure managed rulesets\n - **Custom rules** - Create custom rules\n - **Rate limiting rules** - Configure rate limits\n3. Click **Deploy** or **Create rule**\n\n**Testing**: Use Security Events to test expressions before deploying.\n\n## Wrangler Integration\n\nWAF configuration is zone-level (not Worker-specific). Configuration methods:\n- Dashboard UI\n- Cloudflare API via SDK\n- Terraform/Pulumi (IaC)\n\n**Workers benefit from WAF automatically** - no Worker code changes needed.\n\n**Example: Query WAF API from Worker**:\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n return fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/rulesets`, {\n headers: { 'Authorization': `Bearer ${env.CF_API_TOKEN}` },\n });\n },\n};\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/waf/gotchas.md", "content": "# Gotchas & Troubleshooting\n\n## Execution Order\n\n**Problem:** Rules execute in unexpected order\n**Cause:** Misunderstanding phase execution\n**Solution:**\n\nPhases execute sequentially (can't be changed):\n1. `http_request_firewall_custom` - Custom rules\n2. `http_request_firewall_managed` - Managed rulesets\n3. `http_ratelimit` - Rate limiting\n\nWithin phase: top-to-bottom, first match wins (unless `skip`)\n\n```typescript\n// WRONG: Can't mix phase-specific actions\nawait client.rulesets.create({\n phase: 'http_request_firewall_custom',\n rules: [\n { action: 'block', expression: 'cf.waf.score gt 50' },\n { action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG\n ],\n});\n\n// CORRECT: Separate rulesets per phase\nawait client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });\nawait client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });\n```\n\n## Expression Errors\n\n**Problem:** Syntax errors prevent deployment\n**Cause:** Invalid field/operator/syntax\n**Solution:**\n\n```typescript\n// Common mistakes\n'http.request.path' → 'http.request.uri.path' // Correct field\n'ip.geoip.country eq US' → 'ip.geoip.country eq \"US\"' // Quote strings\n'http.user_agent eq \"Mozilla\"' → 'lower(http.user_agent) contains \"mozilla\"' // Case sensitivity\n'matches \".*[.jpg\"' → 'matches \".*\\\\.jpg$\"' // Valid regex\n```\n\nTest expressions in Security Events before deploying.\n\n## Skip Rule Pitfalls\n\n**Problem:** Skip rules don't work as expected\n**Cause:** Misunderstanding skip scope\n**Solution:**\n\nSkip types:\n- `ruleset: 'current'` - Skip remaining rules in current ruleset only\n- `phases: ['phase_name']` - Skip entire phases\n\n```typescript\n// WRONG: Trying to skip managed rules from custom phase\n// In http_request_firewall_custom:\n{\n action: 'skip',\n action_parameters: { ruleset: 'current' },\n expression: 'ip.src in {192.0.2.0/24}',\n}\n// This only skips remaining custom rules, not managed rules\n\n// CORRECT: Skip specific phases\n{\n action: 'skip',\n action_parameters: {\n phases: ['http_request_firewall_managed', 'http_ratelimit'],\n },\n expression: 'ip.src in {192.0.2.0/24}',\n}\n```\n\n## Update Replaces All Rules\n\n**Problem:** Updating ruleset deletes other rules\n**Cause:** `update()` replaces entire rule list\n**Solution:**\n\n```typescript\n// WRONG: This deletes all existing rules!\nawait client.rulesets.update({\n zone_id: 'zone_id',\n ruleset_id: 'ruleset_id',\n rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],\n});\n\n// CORRECT: Get existing rules first\nconst ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });\nawait client.rulesets.update({\n zone_id: 'zone_id',\n ruleset_id: 'ruleset_id',\n rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],\n});\n```\n\n## Override Conflicts\n\n**Problem:** Managed ruleset overrides don't apply\n**Cause:** Rule ID doesn't exist or category name incorrect\n**Solution:**\n\n```typescript\n// List managed ruleset rules to find IDs\nconst ruleset = await client.rulesets.get({\n zone_id: 'zone_id',\n ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',\n});\nconsole.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));\n\n// Use correct IDs in overrides\n{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', \n overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }\n```\n\n## False Positives\n\n**Problem:** Legitimate traffic blocked\n**Cause:** Aggressive rules/thresholds\n**Solution:**\n\n1. Start with log mode: `overrides: { action: 'log' }`\n2. Review Security Events to identify false positives\n3. Override specific rules: `overrides: { rules: [{ id: 'rule_id', action: 'log' }] }`\n\n## Rate Limiting NAT Issues\n\n**Problem:** Users behind NAT hit rate limits too quickly\n**Cause:** Multiple users sharing single IP\n**Solution:**\n\nAdd more characteristics: User-Agent, session cookie, or authorization header\n```typescript\n{\n action: 'block',\n expression: 'http.request.uri.path starts_with \"/api\"',\n action_parameters: {\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies[\"session\"][0]'],\n period: 60,\n requests_per_period: 100,\n },\n },\n}\n```\n\n## Performance Issues\n\n**Problem:** Increased latency\n**Cause:** Complex expressions, excessive rules\n**Solution:**\n\n1. Skip static assets early: `action: 'skip'` for `\\\\.(jpg|css|js)$`\n2. Path-based deployment: Only run managed on `/api` or `/admin`\n3. Disable unused categories: `{ category: 'wordpress', enabled: false }`\n4. Prefer string operators over regex: `starts_with` vs `matches`\n\n## Limits & Quotas\n\n| Resource | Free | Pro | Business | Enterprise |\n|----------|------|-----|----------|------------|\n| Custom rules | 5 | 20 | 100 | 1000 |\n| Rate limiting rules | 1 | 10 | 25 | 100 |\n| Rule expression length | 4096 chars | 4096 chars | 4096 chars | 4096 chars |\n| Rules per ruleset | 75 | 75 | 400 | 1000 |\n| Managed rulesets | Yes | Yes | Yes | Yes |\n| Rate limit characteristics | 2 | 3 | 5 | 5 |\n\n**Important Notes:**\n- Rules execute in order; first match wins (except skip rules)\n- Expression evaluation stops at first `false` in AND chains\n- `matches` regex operator is slower than string operators\n- Rate limit counting happens before mitigation\n\n## API Errors\n\n**Problem:** API calls fail with cryptic errors\n**Cause:** Invalid parameters or permissions\n**Solution:**\n\n```typescript\n// Error: \"Invalid phase\" → Use exact phase name\nphase: 'http_request_firewall_custom'\n\n// Error: \"Ruleset already exists\" → Use update() or list first\nconst rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });\nif (rulesets.result.length > 0) {\n await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });\n}\n\n// Error: \"Action not supported\" → Check phase/action compatibility\n// 'execute' only in http_request_firewall_managed\n// Rate limit config only in http_ratelimit phase\n\n// Error: \"Expression parse error\" → Common fixes:\n'ip.geoip.country eq \"US\"' // Quote strings\n'cf.waf.score gt 40' // Use 'gt' not '>'\n'http.request.uri.path' // Not 'http.request.path'\n```\n\n**Tip**: Test expressions in dashboard Security Events before deploying.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/waf/patterns.md", "content": "# Common Patterns\n\n## Deploy Managed Rulesets\n\n```typescript\n// Deploy Cloudflare Managed Ruleset (default)\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_managed',\n name: 'Cloudflare Managed Ruleset',\n rules: [{\n action: 'execute',\n action_parameters: {\n id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed\n // Or: '4814384a9e5d4991b9815dcfc25d2f1f' for OWASP CRS\n // Or: 'c2e184081120413c86c3ab7e14069605' for Exposed Credentials\n },\n expression: 'true', // All requests\n // Or: 'http.request.uri.path starts_with \"/api\"' for specific paths\n enabled: true,\n }],\n});\n```\n\n## Override Managed Ruleset\n\n```typescript\nawait client.rulesets.create({\n zone_id: 'zone_id',\n phase: 'http_request_firewall_managed',\n rules: [{\n action: 'execute',\n action_parameters: {\n id: 'efb7b8c949ac4650a09736fc376e9aee',\n overrides: {\n // Override specific rules\n rules: [\n { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' },\n { id: '75a0060762034b9dad4e883afc121b4c', enabled: false },\n ],\n // Override categories: wordpress, sqli, xss, rce, etc.\n categories: [\n { category: 'wordpress', enabled: false },\n { category: 'sqli', action: 'log' },\n ],\n },\n },\n expression: 'true',\n }],\n});\n```\n\n## Custom Rules\n\n```typescript\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_custom',\n name: 'Custom WAF Rules',\n rules: [\n // Attack score-based\n { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },\n { action: 'challenge', expression: 'cf.waf.score gt 20', enabled: true },\n \n // Specific attack types\n { action: 'block', expression: 'cf.waf.score.sqli gt 30 or cf.waf.score.xss gt 30', enabled: true },\n \n // Geographic blocking\n { action: 'block', expression: 'ip.geoip.country in {\"CN\" \"RU\"}', enabled: true },\n ],\n});\n```\n\n## Rate Limiting\n\n```typescript\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_ratelimit',\n name: 'Rate Limits',\n rules: [\n // Per-IP global limit\n {\n action: 'block',\n expression: 'true',\n action_parameters: {\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src'],\n period: 60,\n requests_per_period: 100,\n mitigation_timeout: 600,\n },\n },\n },\n \n // Login endpoint (stricter)\n {\n action: 'block',\n expression: 'http.request.uri.path eq \"/api/login\"',\n action_parameters: {\n ratelimit: {\n characteristics: ['ip.src'],\n period: 60,\n requests_per_period: 5,\n mitigation_timeout: 600,\n },\n },\n },\n \n // API writes only (using counting_expression)\n {\n action: 'block',\n expression: 'http.request.uri.path starts_with \"/api\"',\n action_parameters: {\n ratelimit: {\n characteristics: ['cf.colo.id', 'ip.src'],\n period: 60,\n requests_per_period: 50,\n counting_expression: 'http.request.method ne \"GET\"',\n },\n },\n },\n ],\n});\n```\n\n## Skip Rules\n\n```typescript\nawait client.rulesets.create({\n zone_id: 'zone_id',\n kind: 'zone',\n phase: 'http_request_firewall_custom',\n name: 'Skip Rules',\n rules: [\n // Skip static assets (current ruleset only)\n {\n action: 'skip',\n action_parameters: { ruleset: 'current' },\n expression: 'http.request.uri.path matches \"\\\\.(jpg|css|js|woff2?)$\"',\n },\n \n // Skip all WAF phases for trusted IPs\n {\n action: 'skip',\n action_parameters: {\n phases: ['http_request_firewall_managed', 'http_ratelimit'],\n },\n expression: 'ip.src in {192.0.2.0/24}',\n },\n ],\n});\n```\n\n## Complete Setup Example\n\nCombine all three phases for comprehensive protection:\n\n```typescript\nconst client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });\nconst zoneId = process.env.ZONE_ID;\n\n// 1. Custom rules (execute first)\nawait client.rulesets.create({\n zone_id: zoneId,\n phase: 'http_request_firewall_custom',\n rules: [\n { action: 'skip', action_parameters: { phases: ['http_request_firewall_managed', 'http_ratelimit'] }, expression: 'ip.src in {192.0.2.0/24}' },\n { action: 'block', expression: 'cf.waf.score gt 50' },\n { action: 'managed_challenge', expression: 'cf.waf.score gt 20' },\n ],\n});\n\n// 2. Managed ruleset (execute second)\nawait client.rulesets.create({\n zone_id: zoneId,\n phase: 'http_request_firewall_managed',\n rules: [{\n action: 'execute',\n action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', overrides: { categories: [{ category: 'wordpress', enabled: false }] } },\n expression: 'true',\n }],\n});\n\n// 3. Rate limiting (execute third)\nawait client.rulesets.create({\n zone_id: zoneId,\n phase: 'http_ratelimit',\n rules: [\n { action: 'block', expression: 'true', action_parameters: { ratelimit: { characteristics: ['cf.colo.id', 'ip.src'], period: 60, requests_per_period: 100, mitigation_timeout: 600 } } },\n { action: 'block', expression: 'http.request.uri.path eq \"/api/login\"', action_parameters: { ratelimit: { characteristics: ['ip.src'], period: 60, requests_per_period: 5, mitigation_timeout: 600 } } },\n ],\n});\n```" }, { "path": "skills/.curated/cloudflare-deploy/references/web-analytics/README.md", "content": "# Cloudflare Web Analytics\n\nPrivacy-first web analytics providing Core Web Vitals, traffic metrics, and user insights without compromising visitor privacy.\n\n## Overview\n\nCloudflare Web Analytics provides:\n- **Core Web Vitals** - LCP, FID, CLS, INP, TTFB monitoring\n- **Page views & visits** - Traffic patterns without cookies\n- **Referrers & paths** - Traffic sources and popular pages\n- **Device & browser data** - User agent breakdown\n- **Geographic data** - Country-level visitor distribution\n- **Privacy-first** - No cookies, fingerprinting, or PII collection\n- **Free** - No cost, unlimited pageviews\n\n**Important:** Web Analytics is **dashboard-only**. No API exists for programmatic data access.\n\n## Quick Start Decision Tree\n\n```\nIs your site proxied through Cloudflare?\n├─ YES → Use automatic injection (configuration.md)\n│ ├─ Enable auto-injection in dashboard\n│ └─ No code changes needed (unless Cache-Control: no-transform)\n│\n└─ NO → Use manual beacon integration (integration.md)\n ├─ Add JS snippet to HTML\n ├─ Use spa: true for React/Vue/Next.js\n └─ Configure CSP if needed\n```\n\n## Reading Order\n\n1. **[configuration.md](configuration.md)** - Setup for proxied vs non-proxied sites\n2. **[integration.md](integration.md)** - Framework-specific beacon integration (React, Next.js, Vue, Nuxt, etc.)\n3. **[patterns.md](patterns.md)** - Common use cases (performance monitoring, GDPR consent, multi-site tracking)\n4. **[gotchas.md](gotchas.md)** - Troubleshooting (SPA tracking, CSP issues, hash routing limitations)\n\n## When to Use Each File\n\n- **Setting up for first time?** → Start with configuration.md\n- **Using React/Next.js/Vue/Nuxt?** → Go to integration.md for framework code\n- **Need GDPR consent loading?** → See patterns.md\n- **Beacon not loading or no data?** → Check gotchas.md\n- **SPA not tracking navigation?** → See integration.md for `spa: true` config\n\n## Key Concepts\n\n### Proxied vs Non-Proxied Sites\n\n| Type | Description | Beacon Injection | Limit |\n|------|-------------|------------------|-------|\n| **Proxied** | DNS through Cloudflare (orange cloud) | Automatic or manual | Unlimited |\n| **Non-proxied** | External hosting, manual beacon | Manual only | 10 sites max |\n\n### SPA Mode\n\n**Critical for modern frameworks:**\n```json\n{\"token\": \"YOUR_TOKEN\", \"spa\": true}\n```\n\nWithout `spa: true`, client-side navigation (React Router, Vue Router, Next.js routing) will NOT be tracked. Only initial page loads will register.\n\n### CSP Requirements\n\nIf using Content Security Policy, allow both domains:\n```\nscript-src https://static.cloudflareinsights.com https://cloudflareinsights.com;\n```\n\n## Features\n\n### Core Web Vitals Debugging\n- **LCP (Largest Contentful Paint)** - Identifies slow-loading hero images/elements\n- **FID (First Input Delay)** - Interaction responsiveness (legacy metric)\n- **INP (Interaction to Next Paint)** - Modern interaction responsiveness metric\n- **CLS (Cumulative Layout Shift)** - Visual stability issues\n- **TTFB (Time to First Byte)** - Server response performance\n\nDashboard shows top 5 problematic elements with CSS selectors for debugging.\n\n### Traffic Filters\n- **Bot filtering** - Exclude automated traffic from metrics\n- **Date ranges** - Custom time period analysis\n- **Geographic** - Country-level filtering\n- **Device type** - Desktop, mobile, tablet breakdown\n- **Browser/OS** - User agent filtering\n\n### Rules (Advanced - Plan-dependent)\n\nCreate custom tracking rules for advanced configurations:\n\n**Sample Rate Rules:**\n- Reduce data collection percentage for high-traffic sites\n- Example: Track only 50% of visitors to reduce volume\n\n**Path-Based Rules:**\n- Different behavior per route\n- Example: Exclude `/admin/*` or `/internal/*` from tracking\n\n**Host-Based Rules:**\n- Multi-domain configurations\n- Example: Separate tracking for staging vs production subdomains\n\n**Availability:** Rules feature depends on your Cloudflare plan. Check dashboard under Web Analytics → Rules to see if available. Free plans may have limited or no access.\n\n## Plan Limits\n\n| Feature | Free | Notes |\n|---------|------|-------|\n| Proxied sites | Unlimited | DNS through Cloudflare |\n| Non-proxied sites | 10 | External hosting |\n| Pageviews | Unlimited | No volume limits |\n| Data retention | 6 months | Rolling window |\n| Rules | Plan-dependent | Check dashboard |\n\n## Privacy & Compliance\n\n- **No cookies** - Zero client-side storage\n- **No fingerprinting** - No tracking across sites\n- **No PII** - IP addresses not stored\n- **GDPR-friendly** - Minimal data collection\n- **CCPA-compliant** - No personal data sale\n\n**EU opt-out:** Dashboard option to exclude EU visitor data entirely.\n\n## Limitations\n\n- **Dashboard-only** - No API for programmatic access\n- **No real-time** - 5-10 minute data delay\n- **No custom events** - Automatic pageview/navigation tracking only\n- **History API only** - Hash-based routing (`#/path`) not supported\n- **No session replay** - Metrics only, no user recordings\n- **No form tracking** - Page navigation tracking only\n\n## See Also\n\n- [Cloudflare Web Analytics Docs](https://developers.cloudflare.com/analytics/web-analytics/)\n- [Core Web Vitals Guide](https://web.dev/vitals/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/web-analytics/configuration.md", "content": "# Configuration\n\n## Setup Methods\n\n### Proxied Sites (Automatic)\n\nDashboard → Web Analytics → Add site → Select hostname → Done\n\n| Injection Option | Description |\n|------------------|-------------|\n| Enable | Auto-inject for all visitors (default) |\n| Enable, excluding EU | No injection for EU (GDPR) |\n| Enable with manual snippet | You add beacon manually |\n| Disable | Pause tracking |\n\n**Fails if response has:** `Cache-Control: public, no-transform`\n\n**CSP required:**\n```\nscript-src https://static.cloudflareinsights.com https://cloudflareinsights.com;\n```\n\n### Non-Proxied Sites (Manual)\n\nDashboard → Web Analytics → Add site → Enter hostname → Copy snippet\n\n```html\n\n```\n\n**Limits:** 10 non-proxied sites per account\n\n## SPA Mode\n\n**Enable `spa: true` for:** React Router, Next.js, Vue Router, Nuxt, SvelteKit, Angular\n\n**Keep `spa: false` for:** Traditional multi-page apps, static sites, WordPress\n\n**Hash routing (`#/path`) NOT supported** - use History API routing.\n\n## Token Management\n\n- Found in: Dashboard → Web Analytics → Manage site\n- **Not secrets** - domain-locked, safe to expose in HTML\n- Each site gets unique token\n\n## Environment Config\n\n```typescript\n// Only load in production\nif (process.env.NODE_ENV === 'production') {\n // Load beacon\n}\n```\n\nOr use environment-specific tokens via env vars.\n\n## Verify Installation\n\n1. DevTools Network → filter `cloudflareinsights` → see `beacon.min.js` + data request\n2. No CSP/CORS errors in console\n3. Dashboard shows pageviews after 5-10 min delay\n\n## Rules (Plan-dependent)\n\nConfigure in dashboard for:\n- **Sample rate** - reduce collection % for high-traffic\n- **Path-based** - different behavior per route\n- **Host-based** - separate tracking per domain\n\n## Data Retention\n\n- 6 months rolling window\n- 1-hour bucket granularity\n- No raw export, dashboard only\n" }, { "path": "skills/.curated/cloudflare-deploy/references/web-analytics/gotchas.md", "content": "# Web Analytics Gotchas\n\n## Critical Issues\n\n### SPA Navigation Not Tracked\n\n**Symptom:** Only initial pageload counted \n**Fix:** Add `spa: true`:\n```html\n\n```\n\n### CSP Blocking Beacon\n\n**Symptom:** Console error \"Refused to load script\" \n**Fix:** Allow both domains:\n```\nscript-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com;\n```\n\n### Hash-Based Routing Unsupported\n\n**Symptom:** `#/path` URLs not tracked \n**Fix:** Migrate to History API (`BrowserRouter`, not `HashRouter`). No workaround for hash routing.\n\n### No Data Appearing\n\n**Causes & Fixes:**\n1. **Delay** - Wait 5-15 minutes\n2. **Wrong token** - Verify matches dashboard exactly\n3. **Script blocked** - Check DevTools Network tab for beacon.min.js\n4. **Domain mismatch** - Dashboard site must match actual URL\n\n### Auto-Injection Fails\n\n**Cause:** `Cache-Control: no-transform` header \n**Fix:** Remove `no-transform` or install beacon manually\n\n### Duplicate Pageviews\n\n**Cause:** Multiple beacon scripts \n**Fix:** Keep only one beacon per page\n\n## Configuration Issues\n\n| Issue | Fix |\n|-------|-----|\n| 10-site limit reached | Delete old sites or proxy through CF (unlimited) |\n| Token not recognized | Use exact alphanumeric token from dashboard |\n\n## Framework-Specific\n\n### Next.js Hydration Warning\n\n```tsx\n\n```\n\nPlace before closing `` tag.\n\n## Framework Examples\n\n| Framework | Location | Notes |\n|-----------|----------|-------|\n| React/Vite | `public/index.html` | Add `spa: true` |\n| Next.js App Router | `app/layout.tsx` | Use `\n```\n\nWithout `spa: true`: only initial pageload tracked.\n\n## Staging/Production Separation\n\n```typescript\n// Use env-specific tokens\nconst token = process.env.NEXT_PUBLIC_CF_ANALYTICS_TOKEN;\n// .env.production: production token\n// .env.staging: staging token (or empty to disable)\n```\n\n## Bot Filtering\n\nDashboard → Filters → \"Exclude Bot Traffic\"\n\nFilters: Search crawlers, monitoring services, known bots. \nNot filtered: Headless browsers (Playwright/Puppeteer).\n\n## Ad-Blocker Impact\n\n~25-40% of users may block `cloudflareinsights.com`. No official workaround.\nDashboard shows minimum baseline; use server logs for complete picture.\n\n## Limitations\n\n- No UTM parameter tracking\n- No webhooks/alerts/API\n- No custom beacon domains\n- Max 10 non-proxied sites\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workerd/README.md", "content": "# Workerd Runtime\n\nV8-based JS/Wasm runtime powering Cloudflare Workers. Use as app server, dev tool, or HTTP proxy.\n\n## ⚠️ IMPORTANT SECURITY NOTICE\n**workerd is NOT a hardened sandbox.** Do not run untrusted code. It's designed for deploying YOUR code locally/self-hosted, not multi-tenant SaaS. Cloudflare production adds security layers not present in open-source workerd.\n\n## Decision Tree: When to Use What\n\n**95% of users:** Use Wrangler\n- Local development: `wrangler dev` (uses workerd internally)\n- Deployment: `wrangler deploy` (deploys to Cloudflare)\n- Types: `wrangler types` (generates TypeScript types)\n\n**Use raw workerd directly only if:**\n- Self-hosting Workers runtime in production\n- Embedding runtime in C++ application\n- Custom tooling/testing infrastructure\n- Debugging workerd-specific behavior\n\n**Never use workerd for:**\n- Running untrusted/user-submitted code\n- Multi-tenant isolation (not hardened)\n- Production without additional security layers\n\n## Key Features\n- **Standards-based**: Fetch API, Web Crypto, Streams, WebSocket\n- **Nanoservices**: Service bindings with local call performance\n- **Capability security**: Explicit bindings prevent SSRF\n- **Backwards compatible**: Version = max compat date supported\n\n## Architecture\n```\nConfig (workerd.capnp)\n├── Services (workers/endpoints)\n├── Sockets (HTTP/HTTPS listeners)\n└── Extensions (global capabilities)\n```\n\n## Quick Start\n```bash\nworkerd serve config.capnp\nworkerd compile config.capnp myConfig -o binary\nworkerd test config.capnp\n```\n\n## Platform Support & Beta Status\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| Linux (x64) | Stable | Primary platform |\n| macOS (x64/ARM) | Stable | Full support |\n| Windows | Beta | Use WSL2 for best results |\n| Linux (ARM64) | Experimental | Limited testing |\n\nworkerd is in **active development**. Breaking changes possible. Pin versions in production.\n\n## Core Concepts\n- **Service**: Named endpoint (worker/network/disk/external)\n- **Binding**: Capability-based resource access (KV/DO/R2/services)\n- **Compatibility date**: Feature gate (always set!)\n- **Modules**: ES modules (recommended) or service worker syntax\n\n## Reading Order (Progressive Disclosure)\n\n**Start here:**\n1. This README (overview, decision tree)\n2. [patterns.md](./patterns.md) - Common workflows, framework examples\n\n**When you need details:**\n3. [configuration.md](./configuration.md) - Config format, services, bindings\n4. [api.md](./api.md) - Runtime APIs, TypeScript types\n5. [gotchas.md](./gotchas.md) - Common errors, debugging\n\n## Related References\n- [workers](../workers/) - Workers runtime API documentation\n- [miniflare](../miniflare/) - Testing tool built on workerd\n- [wrangler](../wrangler/) - CLI that uses workerd for local dev\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workerd/api.md", "content": "# Workerd APIs\n\n## Worker Code (JS/TS)\n\n### ES Modules (Recommended)\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n const value = await env.KV.get(\"key\"); // Bindings in env\n const response = await env.API.fetch(request); // Service binding\n ctx.waitUntil(logRequest(request)); // Background task\n return new Response(\"OK\");\n },\n async adminApi(request, env, ctx) { /* Named entrypoint */ },\n async queue(batch, env, ctx) { /* Queue consumer */ },\n async scheduled(event, env, ctx) { /* Cron handler */ }\n};\n```\n\n### TypeScript Types\n\n**Generate from wrangler.toml (Recommended):**\n```bash\nwrangler types # Output: worker-configuration.d.ts\n```\n\n**Manual types:**\n```typescript\ninterface Env {\n API: Fetcher;\n CACHE: KVNamespace;\n STORAGE: R2Bucket;\n ROOMS: DurableObjectNamespace;\n API_KEY: string;\n}\n\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n return new Response(await env.CACHE.get(\"key\"));\n }\n};\n```\n\n**Setup:**\n```bash\nnpm install -D @cloudflare/workers-types\n```\n\n```json\n// tsconfig.json\n{\"compilerOptions\": {\"types\": [\"@cloudflare/workers-types\"]}}\n```\n\n### Service Worker Syntax (Legacy)\n```javascript\naddEventListener('fetch', event => {\n event.respondWith(handleRequest(event.request));\n});\n\nasync function handleRequest(request) {\n const value = await KV.get(\"key\"); // Bindings as globals\n return new Response(\"OK\");\n}\n```\n\n### Durable Objects\n```javascript\nexport class Room {\n constructor(state, env) { this.state = state; this.env = env; }\n \n async fetch(request) {\n const url = new URL(request.url);\n if (url.pathname === \"/increment\") {\n const value = (await this.state.storage.get(\"counter\")) || 0;\n await this.state.storage.put(\"counter\", value + 1);\n return new Response(String(value + 1));\n }\n return new Response(\"Not found\", {status: 404});\n }\n}\n```\n\n### RPC Between Services\n```javascript\n// Caller: env.AUTH.validateToken(token) returns structured data\nconst user = await env.AUTH.validateToken(request.headers.get(\"Authorization\"));\n\n// Callee: export methods that return data\nexport default {\n async validateToken(token) { return {id: 123, name: \"Alice\"}; }\n};\n```\n\n## Web Platform APIs\n\n### Fetch\n- `fetch()`, `Request`, `Response`, `Headers`\n- `AbortController`, `AbortSignal`\n\n### Streams\n- `ReadableStream`, `WritableStream`, `TransformStream`\n- Byte streams, BYOB readers\n\n### Web Crypto\n- `crypto.subtle` (encrypt/decrypt/sign/verify)\n- `crypto.randomUUID()`, `crypto.getRandomValues()`\n\n### Encoding\n- `TextEncoder`, `TextDecoder`\n- `atob()`, `btoa()`\n\n### Web Standards\n- `URL`, `URLSearchParams`\n- `Blob`, `File`, `FormData`\n- `WebSocket`\n\n### Server-Sent Events (EventSource)\n```javascript\n// Server-side SSE\nconst { readable, writable } = new TransformStream();\nconst writer = writable.getWriter();\nwriter.write(new TextEncoder().encode('data: Hello\\n\\n'));\nreturn new Response(readable, {headers: {'Content-Type': 'text/event-stream'}});\n```\n\n### HTMLRewriter (HTML Parsing/Transformation)\n```javascript\nconst response = await fetch('https://example.com');\nreturn new HTMLRewriter()\n .on('a[href]', {\n element(el) {\n el.setAttribute('href', `/proxy?url=${encodeURIComponent(el.getAttribute('href'))}`);\n }\n })\n .on('script', { element(el) { el.remove(); } })\n .transform(response);\n```\n\n### TCP Sockets (Experimental)\n```javascript\nconst socket = await connect({ hostname: 'example.com', port: 80 });\nconst writer = socket.writable.getWriter();\nawait writer.write(new TextEncoder().encode('GET / HTTP/1.1\\r\\n\\r\\n'));\nconst reader = socket.readable.getReader();\nconst { value } = await reader.read();\nreturn new Response(value);\n```\n\n### Performance\n- `performance.now()`, `performance.timeOrigin`\n- `setTimeout()`, `setInterval()`, `queueMicrotask()`\n\n### Console\n- `console.log()`, `console.error()`, `console.warn()`\n\n### Node.js Compat (`nodejs_compat` flag)\n```javascript\nimport { Buffer } from 'node:buffer';\nimport { randomBytes } from 'node:crypto';\n\nconst buf = Buffer.from('Hello');\nconst random = randomBytes(16);\n```\n\n**Available:** `node:buffer`, `node:crypto`, `node:stream`, `node:util`, `node:events`, `node:assert`, `node:path`, `node:querystring`, `node:url`\n**NOT available:** `node:fs`, `node:http`, `node:net`, `node:child_process`\n\n## CLI Commands\n\n```bash\nworkerd serve config.capnp [constantName] # Start server\nworkerd serve config.capnp --socket-addr http=*:3000 --verbose\nworkerd compile config.capnp constantName -o binary # Compile to binary\nworkerd test config.capnp [--test-only=test.js] # Run tests\n```\n\n## Wrangler Integration\n\nUse Wrangler for development:\n```bash\nwrangler dev # Uses workerd internally\nwrangler types # Generate TypeScript types from wrangler.toml\n```\n\nSee [patterns.md](./patterns.md) for usage examples, [configuration.md](./configuration.md) for config details.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workerd/configuration.md", "content": "# Workerd Configuration\n\n## Basic Structure\n```capnp\nusing Workerd = import \"/workerd/workerd.capnp\";\n\nconst config :Workerd.Config = (\n services = [(name = \"main\", worker = .mainWorker)],\n sockets = [(name = \"http\", address = \"*:8080\", http = (), service = \"main\")]\n);\n\nconst mainWorker :Workerd.Worker = (\n modules = [(name = \"index.js\", esModule = embed \"src/index.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [...]\n);\n```\n\n## Services\n**Worker**: Run JS/Wasm code\n```capnp\n(name = \"api\", worker = (\n modules = [(name = \"index.js\", esModule = embed \"index.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [...]\n))\n```\n\n**Network**: Internet access\n```capnp\n(name = \"internet\", network = (allow = [\"public\"], tlsOptions = (trustBrowserCas = true)))\n```\n\n**External**: Reverse proxy\n```capnp\n(name = \"backend\", external = (address = \"api.com:443\", http = (style = tls)))\n```\n\n**Disk**: Static files\n```capnp\n(name = \"assets\", disk = (path = \"/var/www\", writable = false))\n```\n\n## Sockets\n```capnp\n(name = \"http\", address = \"*:8080\", http = (), service = \"main\")\n(name = \"https\", address = \"*:443\", https = (options = (), tlsOptions = (keypair = (...))), service = \"main\")\n(name = \"app\", address = \"unix:/tmp/app.sock\", http = (), service = \"main\")\n```\n\n## Worker Formats\n```capnp\n# ES Modules (recommended)\nmodules = [(name = \"index.js\", esModule = embed \"src/index.js\"), (name = \"wasm.wasm\", wasm = embed \"build/module.wasm\")]\n\n# Service Worker (legacy)\nserviceWorkerScript = embed \"worker.js\"\n\n# CommonJS\n(name = \"legacy.js\", commonJsModule = embed \"legacy.js\", namedExports = [\"foo\"])\n```\n\n## Bindings\nBindings expose resources to workers. ES modules: `env.BINDING`, Service workers: globals.\n\n### Primitive Types\n```capnp\n(name = \"API_KEY\", text = \"secret\") # String\n(name = \"CONFIG\", json = '{\"key\":\"val\"}') # Parsed JSON\n(name = \"DATA\", data = embed \"data.bin\") # ArrayBuffer\n(name = \"DATABASE_URL\", fromEnvironment = \"DB_URL\") # System env var\n```\n\n### Service Binding\n```capnp\n(name = \"AUTH\", service = \"auth-worker\") # Basic\n(name = \"API\", service = (\n name = \"backend\",\n entrypoint = \"adminApi\", # Named export\n props = (json = '{\"role\":\"admin\"}') # ctx.props\n))\n```\n\n### Storage\n```capnp\n(name = \"CACHE\", kvNamespace = \"kv-service\") # KV\n(name = \"STORAGE\", r2Bucket = \"r2-service\") # R2\n(name = \"ROOMS\", durableObjectNamespace = (\n serviceName = \"room-service\",\n className = \"Room\"\n))\n(name = \"FAST\", memoryCache = (\n id = \"cache-id\",\n limits = (maxKeys = 1000, maxValueSize = 1048576)\n))\n```\n\n### Other\n```capnp\n(name = \"TASKS\", queue = \"queue-service\")\n(name = \"ANALYTICS\", analyticsEngine = \"analytics\")\n(name = \"LOADER\", workerLoader = (id = \"dynamic\"))\n(name = \"KEY\", cryptoKey = (format = raw, algorithm = (name = \"HMAC\", hash = \"SHA-256\"), keyData = embed \"key.bin\", usages = [sign, verify], extractable = false))\n(name = \"TRACED\", wrapped = (moduleName = \"tracing\", entrypoint = \"makeTracer\", innerBindings = [(name = \"backend\", service = \"backend\")]))\n```\n\n## Compatibility\n```capnp\ncompatibilityDate = \"2024-01-15\" # Always set!\ncompatibilityFlags = [\"nodejs_compat\", \"streams_enable_constructors\"]\n```\n\nVersion = max compat date. Update carefully after testing.\n\n## Parameter Bindings (Inheritance)\n```capnp\nconst base :Workerd.Worker = (\n modules = [...], compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"API_URL\", parameter = (type = text)), (name = \"DB\", parameter = (type = service))]\n);\n\nconst derived :Workerd.Worker = (\n inherit = \"base-service\",\n bindings = [(name = \"API_URL\", text = \"https://api.com\"), (name = \"DB\", service = \"postgres\")]\n);\n```\n\n## Durable Objects Config\n```capnp\nconst worker :Workerd.Worker = (\n modules = [...],\n compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"ROOMS\", durableObjectNamespace = \"Room\")],\n durableObjectNamespaces = [(className = \"Room\", uniqueKey = \"v1\")],\n durableObjectStorage = (localDisk = \"/var/do\")\n);\n```\n\n## Remote Bindings (Development)\n\nConnect local workerd to production Cloudflare resources:\n\n```capnp\nbindings = [\n # Remote KV (requires API token)\n (name = \"PROD_KV\", kvNamespace = (\n remote = (\n accountId = \"your-account-id\",\n namespaceId = \"your-namespace-id\",\n apiToken = .envVar(\"CF_API_TOKEN\")\n )\n )),\n \n # Remote R2\n (name = \"PROD_R2\", r2Bucket = (\n remote = (\n accountId = \"your-account-id\",\n bucketName = \"my-bucket\",\n apiToken = .envVar(\"CF_API_TOKEN\")\n )\n )),\n \n # Remote Durable Object\n (name = \"PROD_DO\", durableObjectNamespace = (\n remote = (\n accountId = \"your-account-id\",\n scriptName = \"my-worker\",\n className = \"MyDO\",\n apiToken = .envVar(\"CF_API_TOKEN\")\n )\n ))\n]\n```\n\n**Note:** Remote bindings require network access and valid Cloudflare API credentials.\n\n## Logging & Debugging\n```capnp\nlogging = (structuredLogging = true, stdoutPrefix = \"OUT: \", stderrPrefix = \"ERR: \")\nv8Flags = [\"--expose-gc\", \"--max-old-space-size=2048\"] # ⚠️ Unsupported in production\n```\n\nSee [patterns.md](./patterns.md) for multi-service examples, [gotchas.md](./gotchas.md) for config errors.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workerd/gotchas.md", "content": "# Workerd Gotchas\n\n## Common Errors\n\n### \"Missing compatibility date\"\n**Cause:** Compatibility date not set\n**Solution:**\n❌ Wrong:\n```capnp\nconst worker :Workerd.Worker = (\n serviceWorkerScript = embed \"worker.js\"\n)\n```\n\n✅ Correct:\n```capnp\nconst worker :Workerd.Worker = (\n serviceWorkerScript = embed \"worker.js\",\n compatibilityDate = \"2024-01-15\" # Always set!\n)\n```\n\n### Wrong Binding Type\n**Problem:** JSON not parsed\n**Cause:** Using `text = '{\"key\":\"value\"}'` instead of `json`\n**Solution:** Use `json = '{\"key\":\"value\"}'` for parsed objects\n\n### Service vs Namespace\n**Problem:** Cannot create DO instance\n**Cause:** Using `service = \"room-service\"` for Durable Object\n**Solution:** Use `durableObjectNamespace = \"Room\"` for DO bindings\n\n### Module Name Mismatch\n**Problem:** Import fails\n**Cause:** Module name includes path: `name = \"src/index.js\"`\n**Solution:** Use simple names: `name = \"index.js\"`, embed with path\n\n## Network Access\n\n**Problem:** Fetch fails with network error\n**Cause:** No network service configured (workerd has no global fetch)\n**Solution:** Add network service binding:\n```capnp\nservices = [(name = \"internet\", network = (allow = [\"public\"]))]\nbindings = [(name = \"NET\", service = \"internet\")]\n```\n\nOr external service:\n```capnp\nbindings = [(name = \"API\", service = (external = (address = \"api.com:443\", http = (style = tls))))]\n```\n\n### \"Worker not responding\"\n**Cause:** Socket misconfigured, no fetch handler, or port unavailable\n**Solution:** Verify socket `address` matches, worker exports `fetch()`, port available\n\n### \"Binding not found\"\n**Cause:** Name mismatch or service doesn't exist\n**Solution:** Check binding name in config matches code (`env.BINDING` for ES modules)\n\n### \"Module not found\"\n**Cause:** Module name doesn't match import or bad embed path\n**Solution:** Module `name` must match import path exactly, verify `embed` path\n\n### \"Compatibility error\"\n**Cause:** Date not set or API unavailable on that date\n**Solution:** Set `compatibilityDate`, verify API available on that date\n\n## Performance Issues\n\n**Problem:** High memory usage\n**Cause:** Large caches or many isolates\n**Solution:** Set cache limits, reduce isolate count, or use V8 flags (caution)\n\n**Problem:** Slow startup\n**Cause:** Many modules or complex config\n**Solution:** Compile to binary (`workerd compile`), reduce imports\n\n**Problem:** Request timeouts\n**Cause:** External service issues or DNS problems\n**Solution:** Check connectivity, DNS resolution, TLS handshake\n\n## Build Issues\n\n**Problem:** Cap'n Proto syntax errors\n**Cause:** Invalid config or missing schema\n**Solution:** Install capnproto tools, validate: `capnp compile -I. config.capnp`\n\n**Problem:** Embed path not found\n**Cause:** Path relative to config file\n**Solution:** Use correct relative path or absolute path\n\n**Problem:** V8 flags cause crashes\n**Cause:** Unsafe V8 flags\n**Solution:** ⚠️ V8 flags unsupported in production. Test thoroughly before use.\n\n## Security Issues\n\n**Problem:** Hardcoded secrets in config\n**Cause:** `text` binding with secret value\n**Solution:** Use `fromEnvironment` to load from env vars\n\n**Problem:** Overly broad network access\n**Cause:** `network = (allow = [\"*\"])`\n**Solution:** Restrict to `allow = [\"public\"]` or specific hosts\n\n**Problem:** Extractable crypto keys\n**Cause:** `cryptoKey = (extractable = true, ...)`\n**Solution:** Set `extractable = false` unless export required\n\n## Compatibility Changes\n\n**Problem:** Breaking changes after compat date update\n**Cause:** New flags enabled between dates\n**Solution:** Review [compat dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/), test locally first\n\n**Problem:** \"Compatibility date not supported\"\n**Cause:** Workerd version older than compat date\n**Solution:** Update workerd binary (version = max compat date supported)\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| V8 flags | Unsupported in production | Use with caution |\n| Compatibility date | Must match workerd version | Update if mismatch |\n| Module count | Affects startup time | Many imports slow |\n\n## Troubleshooting Steps\n\n1. **Enable verbose logging**: `workerd serve config.capnp --verbose`\n2. **Check logs**: Look for error messages, stack traces\n3. **Validate config**: `capnp compile -I. config.capnp`\n4. **Test bindings**: Log `Object.keys(env)` to verify\n5. **Check versions**: Workerd version vs compat date\n6. **Isolate issue**: Minimal repro config\n7. **Review schema**: [workerd.capnp](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp)\n\nSee [configuration.md](./configuration.md) for config details, [patterns.md](./patterns.md) for working examples, [api.md](./api.md) for runtime APIs.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workerd/patterns.md", "content": "# Workerd Patterns\n\n## Multi-Service Architecture\n```capnp\nconst config :Workerd.Config = (\n services = [\n (name = \"frontend\", worker = (\n modules = [(name = \"index.js\", esModule = embed \"frontend/index.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"API\", service = \"api\")]\n )),\n (name = \"api\", worker = (\n modules = [(name = \"index.js\", esModule = embed \"api/index.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"DB\", service = \"postgres\"), (name = \"CACHE\", kvNamespace = \"kv\")]\n )),\n (name = \"postgres\", external = (address = \"db.internal:5432\", http = ())),\n (name = \"kv\", disk = (path = \"/var/kv\", writable = true))\n ],\n sockets = [(name = \"http\", address = \"*:8080\", http = (), service = \"frontend\")]\n);\n```\n\n## Durable Objects\n```capnp\nconst worker :Workerd.Worker = (\n modules = [(name = \"index.js\", esModule = embed \"index.js\"), (name = \"room.js\", esModule = embed \"room.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"ROOMS\", durableObjectNamespace = \"Room\")],\n durableObjectNamespaces = [(className = \"Room\", uniqueKey = \"v1\")],\n durableObjectStorage = (localDisk = \"/var/do\")\n);\n```\n\n## Dev vs Prod Configs\n```capnp\n# Use parameter bindings for env-specific config\nconst baseWorker :Workerd.Worker = (\n modules = [(name = \"index.js\", esModule = embed \"src/index.js\")],\n compatibilityDate = \"2024-01-15\",\n bindings = [(name = \"API_URL\", parameter = (type = text))]\n);\n\nconst prodWorker :Workerd.Worker = (\n inherit = \"base-service\",\n bindings = [(name = \"API_URL\", text = \"https://api.prod.com\")]\n);\n```\n\n## HTTP Reverse Proxy\n```capnp\nservices = [\n (name = \"proxy\", worker = (serviceWorkerScript = embed \"proxy.js\", compatibilityDate = \"2024-01-15\", bindings = [(name = \"BACKEND\", service = \"backend\")])),\n (name = \"backend\", external = (address = \"internal:8080\", http = ()))\n]\n```\n\n## Local Development\n\n**Recommended:** Use Wrangler\n```bash\nwrangler dev # Uses workerd internally\n```\n\n**Direct workerd:**\n```bash\nworkerd serve config.capnp --socket-addr http=*:3000 --verbose\n```\n\n**Environment variables:**\n```capnp\nbindings = [(name = \"DATABASE_URL\", fromEnvironment = \"DATABASE_URL\")]\n```\n\n## Testing\n```bash\nworkerd test config.capnp\nworkerd test config.capnp --test-only=test.js\n```\n\nTest files must be included in `modules = [...]` config.\n\n## Production Deployment\n\n### Compiled Binary (Recommended)\n```bash\nworkerd compile config.capnp myConfig -o production-server\n./production-server\n```\n\n### Docker\n```dockerfile\nFROM debian:bookworm-slim\nRUN apt-get update && apt-get install -y ca-certificates\nCOPY workerd /usr/local/bin/\nCOPY config.capnp /etc/workerd/\nCOPY src/ /etc/workerd/src/\nEXPOSE 8080\nCMD [\"workerd\", \"serve\", \"/etc/workerd/config.capnp\"]\n```\n\n### Systemd\n```ini\n# /etc/systemd/system/workerd.service\n[Service]\nExecStart=/usr/bin/workerd serve /etc/workerd/config.capnp --socket-fd http=3\nRestart=always\nUser=nobody\n```\n\nSee systemd socket activation docs for complete setup.\n\n## Framework Integration\n\n### Hono\n```javascript\nimport { Hono } from 'hono';\n\nconst app = new Hono();\n\napp.get('/', (c) => c.text('Hello Hono!'));\napp.get('/api/:id', async (c) => {\n const id = c.req.param('id');\n const data = await c.env.KV.get(id);\n return c.json({ id, data });\n});\n\nexport default app;\n```\n\n### itty-router\n```javascript\nimport { Router } from 'itty-router';\n\nconst router = Router();\n\nrouter.get('/', () => new Response('Hello itty!'));\nrouter.get('/api/:id', async (request, env) => {\n const { id } = request.params;\n const data = await env.KV.get(id);\n return Response.json({ id, data });\n});\n\nexport default {\n fetch: (request, env, ctx) => router.handle(request, env, ctx)\n};\n```\n\n## Best Practices\n\n1. **Use ES modules** over service worker syntax\n2. **Explicit bindings** - no global namespace assumptions\n3. **Type safety** - define `Env` interfaces (use `wrangler types`)\n4. **Service isolation** - split concerns into multiple services\n5. **Pin compat date** in production after testing\n6. **Use ctx.waitUntil()** for background tasks\n7. **Handle errors gracefully** with try/catch\n8. **Configure resource limits** on caches/storage\n\n## Common Patterns\n\n### Error Handling\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n try {\n return await handleRequest(request, env);\n } catch (error) {\n console.error(\"Request failed\", error);\n return new Response(\"Internal Error\", {status: 500});\n }\n }\n};\n```\n\n### Background Tasks\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n const response = new Response(\"OK\");\n \n // Fire-and-forget background work\n ctx.waitUntil(\n env.ANALYTICS.put(request.url, Date.now())\n );\n \n return response;\n }\n};\n```\n\nSee [configuration.md](./configuration.md) for config syntax, [api.md](./api.md) for runtime APIs, [gotchas.md](./gotchas.md) for common errors.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/README.md", "content": "# Cloudflare Workers\n\nExpert guidance for building, deploying, and optimizing Cloudflare Workers applications.\n\n## Overview\n\nCloudflare Workers run on V8 isolates (NOT containers/VMs):\n- Extremely fast cold starts (< 1ms)\n- Global deployment across 300+ locations\n- Web standards compliant (fetch, URL, Headers, Request, Response)\n- Support JS/TS, Python, Rust, and WebAssembly\n\n**Key principle**: Workers use web platform APIs wherever possible for portability.\n\n## Module Worker Pattern (Recommended)\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n return new Response('Hello World!');\n },\n};\n```\n\n**Handler parameters**:\n- `request`: Incoming HTTP request (standard Request object)\n- `env`: Environment bindings (KV, D1, R2, secrets, vars)\n- `ctx`: Execution context (`waitUntil`, `passThroughOnException`)\n\n## Essential Commands\n\n```bash\nnpx wrangler dev # Local dev\nnpx wrangler dev --remote # Remote dev (actual resources)\nnpx wrangler deploy # Production\nnpx wrangler deploy --env staging # Specific environment\nnpx wrangler tail # Stream logs\nnpx wrangler secret put API_KEY # Set secret\n```\n\n## When to Use Workers\n\n- API endpoints at the edge\n- Request/response transformation\n- Authentication/authorization layers\n- Static asset optimization\n- A/B testing and feature flags\n- Rate limiting and security\n- Proxy/routing logic\n- WebSocket applications\n\n## Quick Start\n\n```bash\nnpm create cloudflare@latest my-worker -- --type hello-world\ncd my-worker\nnpx wrangler dev\n```\n\n## Handler Signatures\n\n```typescript\n// HTTP requests\nasync fetch(request: Request, env: Env, ctx: ExecutionContext): Promise\n\n// Cron triggers\nasync scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise\n\n// Queue consumer\nasync queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise\n\n// Tail consumer\nasync tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promise\n```\n\n## Resources\n\n**Docs**: https://developers.cloudflare.com/workers/ \n**Examples**: https://developers.cloudflare.com/workers/examples/ \n**Runtime APIs**: https://developers.cloudflare.com/workers/runtime-apis/\n\n## In This Reference\n\n- [Configuration](./configuration.md) - wrangler.jsonc setup, bindings, environments\n- [API](./api.md) - Runtime APIs, bindings, execution context\n- [Patterns](./patterns.md) - Common workflows, testing, optimization\n- [Frameworks](./frameworks.md) - Hono, routing, validation\n- [Gotchas](./gotchas.md) - Common issues, limits, troubleshooting\n\n## Reading Order\n\n| Task | Start With | Then Read |\n|------|------------|-----------|\n| First Worker | README → Configuration → API | Patterns |\n| Add framework | Frameworks | Configuration (bindings) |\n| Add storage/bindings | Configuration → API (binding usage) | See Also links |\n| Debug issues | Gotchas | API (specific binding docs) |\n| Production optimization | Patterns | API (caching, streaming) |\n| Type safety | Configuration (TypeScript) | Frameworks (Hono typing) |\n\n## See Also\n\n- [KV](../kv/README.md) - Key-value storage\n- [D1](../d1/README.md) - SQL database\n- [R2](../r2/README.md) - Object storage\n- [Durable Objects](../durable-objects/README.md) - Stateful coordination\n- [Queues](../queues/README.md) - Message queues\n- [Wrangler](../wrangler/README.md) - CLI tool reference\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/api.md", "content": "# Workers Runtime APIs\n\n## Fetch Handler\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n const url = new URL(request.url);\n if (request.method === 'POST' && url.pathname === '/api') {\n const body = await request.json();\n return new Response(JSON.stringify({ id: 1 }), {\n headers: { 'Content-Type': 'application/json' }\n });\n }\n return fetch(request); // Subrequest to origin\n },\n};\n```\n\n## Execution Context\n\n```typescript\nctx.waitUntil(logAnalytics(request)); // Background work, don't block response\nctx.passThroughOnException(); // Failover to origin on error\n```\n\n**Never** `await` background operations - use `ctx.waitUntil()`.\n\n## Bindings\n\n```typescript\n// KV\nawait env.MY_KV.get('key');\nawait env.MY_KV.put('key', 'value', { expirationTtl: 3600 });\n\n// R2\nconst obj = await env.MY_BUCKET.get('file.txt');\nawait env.MY_BUCKET.put('file.txt', 'content');\n\n// D1\nconst result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1).first();\n\n// D1 Sessions (2024+) - read-after-write consistency\nconst session = env.DB.withSession();\nawait session.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run();\nconst user = await session.prepare('SELECT * FROM users WHERE name = ?').bind('Alice').first(); // Guaranteed fresh\n\n// Queues\nawait env.MY_QUEUE.send({ timestamp: Date.now() });\n\n// Secrets/vars\nconst key = env.API_KEY;\n```\n\n## Cache API\n\n```typescript\nconst cache = caches.default;\nlet response = await cache.match(request);\n\nif (!response) {\n response = await fetch(request);\n response = new Response(response.body, response);\n response.headers.set('Cache-Control', 'max-age=3600');\n ctx.waitUntil(cache.put(request, response.clone())); // Clone before caching\n}\n```\n\n## HTMLRewriter\n\n```typescript\nreturn new HTMLRewriter()\n .on('a[href]', {\n element(el) {\n const href = el.getAttribute('href');\n if (href?.startsWith('http://')) {\n el.setAttribute('href', href.replace('http://', 'https://'));\n }\n }\n })\n .transform(response);\n```\n\n**Use cases**: A/B testing, analytics injection, link rewriting\n\n## WebSockets\n\n### Standard WebSocket\n\n```typescript\nconst [client, server] = Object.values(new WebSocketPair());\n\nserver.accept();\nserver.addEventListener('message', event => {\n server.send(`Echo: ${event.data}`);\n});\n\nreturn new Response(null, { status: 101, webSocket: client });\n```\n\n### WebSocket Hibernation (Recommended for idle connections)\n\n```typescript\n// In Durable Object\nexport class WebSocketDO {\n async webSocketMessage(ws: WebSocket, message: string) {\n ws.send(`Echo: ${message}`);\n }\n \n async webSocketClose(ws: WebSocket, code: number, reason: string) {\n // Cleanup on close\n }\n \n async webSocketError(ws: WebSocket, error: Error) {\n console.error('WebSocket error:', error);\n }\n}\n```\n\nHibernation automatically suspends inactive connections (no CPU cost), wakes on events\n\n## Durable Objects\n\n### RPC Pattern (Recommended 2024+)\n\n```typescript\nexport class Counter {\n private value = 0;\n \n constructor(private state: DurableObjectState) {\n state.blockConcurrencyWhile(async () => {\n this.value = (await state.storage.get('value')) || 0;\n });\n }\n \n // Export methods directly - called via RPC (type-safe, zero serialization)\n async increment(): Promise {\n this.value++;\n await this.state.storage.put('value', this.value);\n return this.value;\n }\n \n async getValue(): Promise {\n return this.value;\n }\n}\n\n// Worker usage:\nconst stub = env.COUNTER.get(env.COUNTER.idFromName('global'));\nconst count = await stub.increment(); // Direct method call, full type safety\n```\n\n### Legacy Fetch Pattern (Pre-2024)\n\n```typescript\nasync fetch(request: Request): Promise {\n const url = new URL(request.url);\n if (url.pathname === '/increment') {\n await this.state.storage.put('value', ++this.value);\n }\n return new Response(String(this.value));\n}\n// Usage: await stub.fetch('http://x/increment')\n```\n\n**When to use DOs**: Real-time collaboration, rate limiting, strongly consistent state\n\n## Other Handlers\n\n```typescript\n// Cron: async scheduled(event, env, ctx) { ctx.waitUntil(doCleanup(env)); }\n// Queue: async queue(batch) { for (const msg of batch.messages) { await process(msg.body); msg.ack(); } }\n// Tail: async tail(events, env) { for (const e of events) if (e.outcome === 'exception') await log(e); }\n```\n\n## Service Bindings\n\n```typescript\n// Worker-to-worker RPC (zero latency, no internet round-trip)\nreturn env.SERVICE_B.fetch(request);\n\n// With RPC (2024+) - same as Durable Objects RPC\nexport class ServiceWorker {\n async getData() { return { data: 'value' }; }\n}\n// Usage: const data = await env.SERVICE_B.getData();\n```\n\n**Benefits**: Type-safe method calls, no HTTP overhead, share code between Workers\n\n## See Also\n\n- [Configuration](./configuration.md) - Binding setup\n- [Patterns](./patterns.md) - Common workflows\n- [KV](../kv/README.md), [D1](../d1/README.md), [R2](../r2/README.md), [Durable Objects](../durable-objects/README.md), [Queues](../queues/README.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/configuration.md", "content": "# Workers Configuration\n\n## wrangler.jsonc (Recommended)\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \n // Bindings (non-inheritable)\n \"vars\": { \"ENVIRONMENT\": \"production\" },\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"abc123\" }],\n \"r2_buckets\": [{ \"binding\": \"MY_BUCKET\", \"bucket_name\": \"my-bucket\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"my-db\", \"database_id\": \"xyz789\" }],\n \n // Environments\n \"env\": {\n \"staging\": {\n \"vars\": { \"ENVIRONMENT\": \"staging\" },\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"staging-id\" }]\n }\n }\n}\n```\n\n## Configuration Rules\n\n**Inheritable**: `name`, `main`, `compatibility_date`, `routes`, `workers_dev` \n**Non-inheritable**: All bindings (`vars`, `kv_namespaces`, `r2_buckets`, etc.) \n**Top-level only**: `migrations`, `keep_vars`, `send_metrics`\n\n**ALWAYS set `compatibility_date` to current date for new projects**\n\n## Bindings\n\n```jsonc\n{\n // Environment variables - access via env.VAR_NAME\n \"vars\": { \"ENVIRONMENT\": \"production\" },\n \n // KV (key-value storage)\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"abc123\" }],\n \n // R2 (object storage)\n \"r2_buckets\": [{ \"binding\": \"MY_BUCKET\", \"bucket_name\": \"my-bucket\" }],\n \n // D1 (SQL database)\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"my-db\", \"database_id\": \"xyz789\" }],\n \n // Durable Objects (stateful coordination)\n \"durable_objects\": {\n \"bindings\": [{ \"name\": \"COUNTER\", \"class_name\": \"Counter\" }]\n },\n \n // Queues (message queues)\n \"queues\": {\n \"producers\": [{ \"binding\": \"MY_QUEUE\", \"queue\": \"my-queue\" }],\n \"consumers\": [{ \"queue\": \"my-queue\", \"max_batch_size\": 10 }]\n },\n \n // Service bindings (worker-to-worker RPC)\n \"services\": [{ \"binding\": \"SERVICE_B\", \"service\": \"service-b\" }],\n \n // Analytics Engine\n \"analytics_engine_datasets\": [{ \"binding\": \"ANALYTICS\" }]\n}\n```\n\n### Secrets\n\nSet via CLI (never in config):\n\n```bash\nnpx wrangler secret put API_KEY\n```\n\nAccess: `env.API_KEY`\n\n### Automatic Provisioning (Beta)\n\nBindings without IDs are auto-created:\n\n```jsonc\n{ \"kv_namespaces\": [{ \"binding\": \"MY_KV\" }] } // ID added on deploy\n```\n\n## Routes & Triggers\n\n```jsonc\n{\n \"routes\": [\n { \"pattern\": \"example.com/*\", \"zone_name\": \"example.com\" }\n ],\n \"triggers\": {\n \"crons\": [\"0 */6 * * *\"] // Every 6 hours\n }\n}\n```\n\n## TypeScript Setup\n\n### Automatic Type Generation (Recommended)\n\n```bash\nnpm install -D @cloudflare/workers-types\nnpx wrangler types # Generates .wrangler/types/runtime.d.ts from wrangler.jsonc\n```\n\n`tsconfig.json`:\n\n```jsonc\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"lib\": [\"ES2022\"],\n \"types\": [\"@cloudflare/workers-types\"]\n },\n \"include\": [\".wrangler/types/**/*.ts\", \"src/**/*\"]\n}\n```\n\nImport generated types:\n\n```typescript\nimport type { Env } from './.wrangler/types/runtime';\n\nexport default {\n async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {\n await env.MY_KV.get('key'); // Fully typed, autocomplete works\n return new Response('OK');\n },\n};\n```\n\nRe-run `npx wrangler types` after changing bindings in wrangler.jsonc\n\n### Manual Type Definition (Legacy)\n\n```typescript\ninterface Env {\n MY_KV: KVNamespace;\n DB: D1Database;\n API_KEY: string;\n}\n```\n\n## Advanced Options\n\n```jsonc\n{\n // Auto-locate compute near data sources\n \"placement\": { \"mode\": \"smart\" },\n \n // Enable Node.js built-ins (Buffer, process, path, etc.)\n \"compatibility_flags\": [\"nodejs_compat_v2\"],\n \n // Observability (10% sampling)\n \"observability\": { \"enabled\": true, \"head_sampling_rate\": 0.1 }\n}\n```\n\n### Node.js Compatibility\n\n`nodejs_compat_v2` enables:\n- `Buffer`, `process.env`, `path`, `stream`\n- CommonJS `require()` for Node modules\n- `node:` imports (e.g., `import { Buffer } from 'node:buffer'`)\n\n**Note:** Adds ~1-2ms cold start overhead. Use Workers APIs (R2, KV) when possible\n\n## Deployment Commands\n\n```bash\nnpx wrangler deploy # Production\nnpx wrangler deploy --env staging\nnpx wrangler deploy --dry-run # Validate only\n```\n\n## See Also\n\n- [API](./api.md) - Runtime APIs and bindings usage\n- [Patterns](./patterns.md) - Deployment strategies\n- [Wrangler](../wrangler/README.md) - CLI reference\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/frameworks.md", "content": "# Workers Frameworks\n\n## Hono (Recommended)\n\nWorkers-native web framework with excellent TypeScript support and middleware ecosystem.\n\n```bash\nnpm install hono\n```\n\n### Basic Setup\n\n```typescript\nimport { Hono } from 'hono';\n\nconst app = new Hono();\n\napp.get('/', (c) => c.text('Hello World!'));\napp.post('/api/users', async (c) => {\n const body = await c.req.json();\n return c.json({ id: 1, ...body }, 201);\n});\n\nexport default app;\n```\n\n### Typed Environment\n\n```typescript\nimport type { Env } from './.wrangler/types/runtime';\n\nconst app = new Hono<{ Bindings: Env }>();\n\napp.get('/data', async (c) => {\n const value = await c.env.MY_KV.get('key'); // Fully typed\n return c.text(value || 'Not found');\n});\n```\n\n### Middleware\n\n```typescript\nimport { cors } from 'hono/cors';\nimport { logger } from 'hono/logger';\n\napp.use('*', logger());\napp.use('/api/*', cors({ origin: '*' }));\n\n// Custom middleware\napp.use('/protected/*', async (c, next) => {\n const auth = c.req.header('Authorization');\n if (!auth?.startsWith('Bearer ')) return c.text('Unauthorized', 401);\n await next();\n});\n```\n\n### Request Validation (Zod)\n\n```typescript\nimport { zValidator } from '@hono/zod-validator';\nimport { z } from 'zod';\n\nconst schema = z.object({\n name: z.string().min(1),\n email: z.string().email(),\n});\n\napp.post('/users', zValidator('json', schema), async (c) => {\n const validated = c.req.valid('json'); // Type-safe, validated data\n return c.json({ id: 1, ...validated });\n});\n```\n\n**Error handling**: Automatic 400 response with validation errors\n\n### Route Groups\n\n```typescript\nconst api = new Hono().basePath('/api');\n\napi.get('/users', (c) => c.json([]));\napi.post('/users', (c) => c.json({ id: 1 }));\n\napp.route('/', api); // Mounts at /api/*\n```\n\n### Error Handling\n\n```typescript\napp.onError((err, c) => {\n console.error(err);\n return c.json({ error: err.message }, 500);\n});\n\napp.notFound((c) => c.json({ error: 'Not Found' }, 404));\n```\n\n### Accessing ExecutionContext\n\n```typescript\nexport default {\n fetch(request: Request, env: Env, ctx: ExecutionContext) {\n return app.fetch(request, env, ctx);\n },\n};\n\n// In route handlers:\napp.get('/log', (c) => {\n c.executionCtx.waitUntil(logRequest(c.req));\n return c.text('OK');\n});\n```\n\n### OpenAPI/Swagger (Hono OpenAPI)\n\n```typescript\nimport { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';\n\nconst app = new OpenAPIHono();\n\nconst route = createRoute({\n method: 'get',\n path: '/users/{id}',\n request: { params: z.object({ id: z.string() }) },\n responses: {\n 200: { description: 'User found', content: { 'application/json': { schema: z.object({ id: z.string() }) } } },\n },\n});\n\napp.openapi(route, (c) => {\n const { id } = c.req.valid('param');\n return c.json({ id });\n});\n\napp.doc('/openapi.json', { openapi: '3.0.0', info: { version: '1.0.0', title: 'API' } });\n```\n\n### Testing with Hono\n\n```typescript\nimport { describe, it, expect } from 'vitest';\nimport app from '../src/index';\n\ndescribe('API', () => {\n it('GET /', async () => {\n const res = await app.request('/');\n expect(res.status).toBe(200);\n expect(await res.text()).toBe('Hello World!');\n });\n});\n```\n\n## Other Frameworks\n\n### itty-router (Minimalist)\n\n```typescript\nimport { Router } from 'itty-router';\n\nconst router = Router();\n\nrouter.get('/users/:id', ({ params }) => new Response(params.id));\n\nexport default { fetch: router.handle };\n```\n\n**Use case**: Tiny bundle size (~500 bytes), simple routing needs\n\n### Worktop (Advanced)\n\n```typescript\nimport { Router } from 'worktop';\n\nconst router = new Router();\n\nrouter.add('GET', '/users/:id', (req, res) => {\n res.send(200, { id: req.params.id });\n});\n\nrouter.listen();\n```\n\n**Use case**: Advanced routing, built-in CORS/cache utilities\n\n## Framework Comparison\n\n| Framework | Bundle Size | TypeScript | Middleware | Validation | Best For |\n|-----------|-------------|------------|------------|------------|----------|\n| Hono | ~12KB | Excellent | Rich | Zod | Production apps |\n| itty-router | ~500B | Good | Basic | Manual | Minimal APIs |\n| Worktop | ~8KB | Good | Advanced | Manual | Complex routing |\n\n## See Also\n\n- [Patterns](./patterns.md) - Common workflows\n- [API](./api.md) - Runtime APIs\n- [Gotchas](./gotchas.md) - Framework-specific issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/gotchas.md", "content": "# Workers Gotchas\n\n## Common Errors\n\n### \"Too much CPU time used\"\n\n**Cause:** Worker exceeded CPU time limit (10ms standard, 30ms unbound) \n**Solution:** Use `ctx.waitUntil()` for background work, offload heavy compute to Durable Objects, or consider Workers AI for ML workloads\n\n### \"Module-Level State Lost\"\n\n**Cause:** Workers are stateless between requests; module-level variables reset unpredictably \n**Solution:** Use KV, D1, or Durable Objects for persistent state; don't rely on module-level variables\n\n### \"Body has already been used\"\n\n**Cause:** Attempting to read response body twice (bodies are streams) \n**Solution:** Clone response before reading: `response.clone()` or read once and create new Response with the text\n\n### \"Node.js module not found\"\n\n**Cause:** Node.js built-ins not available by default \n**Solution:** Use Workers APIs (e.g., R2 for file storage) or enable Node.js compat with `\"compatibility_flags\": [\"nodejs_compat_v2\"]`\n\n### \"Cannot fetch in global scope\"\n\n**Cause:** Attempting to use fetch during module initialization \n**Solution:** Move fetch calls inside handler functions (fetch, scheduled, etc.) where they're allowed\n\n### \"Subrequest depth limit exceeded\"\n\n**Cause:** Too many nested subrequests creating deep call chain \n**Solution:** Flatten request chain or use service bindings for direct Worker-to-Worker communication\n\n### \"D1 read-after-write inconsistency\"\n\n**Cause:** D1 is eventually consistent; reads may not reflect recent writes \n**Solution:** Use D1 Sessions (2024+) to guarantee read-after-write consistency within a session:\n\n```typescript\nconst session = env.DB.withSession();\nawait session.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run();\nconst user = await session.prepare('SELECT * FROM users WHERE name = ?').bind('Alice').first(); // Guaranteed to see Alice\n```\n\n**When to use sessions:** Write → Read patterns, transactions requiring consistency\n\n### \"wrangler types not generating TypeScript definitions\"\n\n**Cause:** Type generation not configured or outdated \n**Solution:** Run `npx wrangler types` after changing bindings in wrangler.jsonc:\n\n```bash\nnpx wrangler types # Generates .wrangler/types/runtime.d.ts\n```\n\nAdd to `tsconfig.json`: `\"include\": [\".wrangler/types/**/*.ts\"]`\n\nThen import: `import type { Env } from './.wrangler/types/runtime';`\n\n### \"Durable Object RPC errors with deprecated fetch pattern\"\n\n**Cause:** Using old `stub.fetch()` pattern instead of RPC (2024+) \n**Solution:** Export methods directly, call via RPC:\n\n```typescript\n// ❌ Old fetch pattern\nexport class MyDO {\n async fetch(request: Request) {\n const { method } = await request.json();\n if (method === 'increment') return new Response(String(await this.increment()));\n }\n async increment() { return ++this.value; }\n}\nconst stub = env.DO.get(id);\nconst res = await stub.fetch('http://x', { method: 'POST', body: JSON.stringify({ method: 'increment' }) });\n\n// ✅ RPC pattern (type-safe, no serialization overhead)\nexport class MyDO {\n async increment() { return ++this.value; }\n}\nconst stub = env.DO.get(id);\nconst count = await stub.increment(); // Direct method call\n```\n\n### \"WebSocket connection closes unexpectedly\"\n\n**Cause:** Worker reaches CPU limit while maintaining WebSocket connection \n**Solution:** Use WebSocket hibernation (2024+) to offload idle connections:\n\n```typescript\nexport class WebSocketDO {\n async webSocketMessage(ws: WebSocket, message: string) {\n // Handle message\n }\n async webSocketClose(ws: WebSocket, code: number) {\n // Cleanup\n }\n}\n```\n\nHibernation automatically suspends inactive connections, wakes on events\n\n### \"Framework middleware not working with Workers\"\n\n**Cause:** Framework expects Node.js primitives (e.g., Express uses Node streams) \n**Solution:** Use Workers-native frameworks (Hono, itty-router, Worktop) or adapt middleware:\n\n```typescript\n// ✅ Hono (Workers-native)\nimport { Hono } from 'hono';\nconst app = new Hono();\napp.use('*', async (c, next) => { /* middleware */ await next(); });\n```\n\nSee [frameworks.md](./frameworks.md) for full patterns\n\n## Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Request size | 100 MB | Maximum incoming request size |\n| Response size | Unlimited | Supports streaming |\n| CPU time (standard) | 10ms | Standard Workers |\n| CPU time (unbound) | 30ms | Unbound Workers |\n| Subrequests | 1000 | Per request |\n| KV reads | 1000 | Per request |\n| KV write size | 25 MB | Maximum per write |\n| Environment size | 5 MB | Total size of env bindings |\n\n## See Also\n\n- [Patterns](./patterns.md) - Best practices\n- [API](./api.md) - Runtime APIs\n- [Configuration](./configuration.md) - Setup\n- [Frameworks](./frameworks.md) - Hono, routing, validation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers/patterns.md", "content": "# Workers Patterns\n\n## Error Handling\n\n```typescript\nclass HTTPError extends Error {\n constructor(public status: number, message: string) { super(message); }\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n try {\n return await handleRequest(request, env);\n } catch (error) {\n if (error instanceof HTTPError) {\n return new Response(JSON.stringify({ error: error.message }), {\n status: error.status, headers: { 'Content-Type': 'application/json' }\n });\n }\n return new Response('Internal Server Error', { status: 500 });\n }\n },\n};\n```\n\n## CORS\n\n```typescript\nconst corsHeaders = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS' };\nif (request.method === 'OPTIONS') return new Response(null, { headers: corsHeaders });\n```\n\n## Routing\n\n```typescript\nconst router = { 'GET /api/users': handleGetUsers, 'POST /api/users': handleCreateUser };\n\nconst handler = router[`${request.method} ${url.pathname}`];\nreturn handler ? handler(request, env) : new Response('Not Found', { status: 404 });\n```\n\n**Production**: Use Hono, itty-router, or Worktop (see [frameworks.md](./frameworks.md))\n\n## Request Validation (Zod)\n\n```typescript\nimport { z } from 'zod';\n\nconst userSchema = z.object({\n name: z.string().min(1).max(100),\n email: z.string().email(),\n age: z.number().int().positive().optional(),\n});\n\nasync function handleCreateUser(request: Request) {\n try {\n const body = await request.json();\n const validated = userSchema.parse(body); // Throws on invalid data\n return new Response(JSON.stringify({ id: 1, ...validated }), {\n status: 201,\n headers: { 'Content-Type': 'application/json' },\n });\n } catch (err) {\n if (err instanceof z.ZodError) {\n return new Response(JSON.stringify({ errors: err.errors }), { status: 400 });\n }\n throw err;\n }\n}\n```\n\n**With Hono**: Use `@hono/zod-validator` for automatic validation (see [frameworks.md](./frameworks.md))\n\n## Performance\n\n```typescript\n// ❌ Sequential\nconst user = await fetch('/api/user/1');\nconst posts = await fetch('/api/posts?user=1');\n\n// ✅ Parallel\nconst [user, posts] = await Promise.all([fetch('/api/user/1'), fetch('/api/posts?user=1')]);\n```\n\n## Streaming\n\n```typescript\nconst stream = new ReadableStream({\n async start(controller) {\n for (let i = 0; i < 1000; i++) {\n controller.enqueue(new TextEncoder().encode(`Item ${i}\\n`));\n if (i % 100 === 0) await new Promise(r => setTimeout(r, 0));\n }\n controller.close();\n }\n});\n```\n\n## Transform Streams\n\n```typescript\nresponse.body.pipeThrough(new TextDecoderStream()).pipeThrough(\n new TransformStream({ transform(chunk, c) { c.enqueue(chunk.toUpperCase()); } })\n).pipeThrough(new TextEncoderStream());\n```\n\n## Testing\n\n```typescript\nimport { describe, it, expect } from 'vitest';\nimport worker from '../src/index';\n\ndescribe('Worker', () => {\n it('returns 200', async () => {\n const req = new Request('http://localhost/');\n const env = { MY_VAR: 'test' };\n const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };\n expect((await worker.fetch(req, env, ctx)).status).toBe(200);\n });\n});\n```\n\n## Deployment\n\n```bash\nnpx wrangler deploy # production\nnpx wrangler deploy --env staging\nnpx wrangler versions upload --message \"Add feature\"\nnpx wrangler rollback\n```\n\n## Monitoring\n\n```typescript\nconst start = Date.now();\nconst response = await handleRequest(request, env);\nctx.waitUntil(env.ANALYTICS.writeDataPoint({\n doubles: [Date.now() - start], blobs: [request.url, String(response.status)]\n}));\n```\n\n## Security & Rate Limiting\n\n```typescript\n// Security headers\nconst security = { 'X-Content-Type-Options': 'nosniff', 'X-Frame-Options': 'DENY' };\n\n// Auth\nconst auth = request.headers.get('Authorization');\nif (!auth?.startsWith('Bearer ')) return new Response('Unauthorized', { status: 401 });\n\n// Gradual rollouts (deterministic user bucketing)\nconst hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(userId));\nif (new Uint8Array(hash)[0] % 100 < rolloutPercent) return newFeature(request);\n```\n\nRate limiting: See [Durable Objects](../durable-objects/README.md)\n\n## R2 Multipart Upload\n\n```typescript\n// For files > 100MB\nconst upload = await env.MY_BUCKET.createMultipartUpload('large-file.bin');\ntry {\n const parts = [];\n for (let i = 0; i < chunks.length; i++) {\n parts.push(await upload.uploadPart(i + 1, chunks[i]));\n }\n await upload.complete(parts);\n} catch (err) { await upload.abort(); throw err; }\n```\n\nParallel uploads, resume on failure, handle files > 5GB\n\n## Workflows (Step Orchestration)\n\n```typescript\nimport { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';\n\nexport class MyWorkflow extends WorkflowEntrypoint {\n async run(event: WorkflowEvent<{ userId: string }>, step: WorkflowStep) {\n const user = await step.do('fetch-user', async () => \n fetch(`/api/users/${event.payload.userId}`).then(r => r.json())\n );\n await step.sleep('wait', '1 hour');\n await step.do('notify', async () => sendEmail(user.email));\n }\n}\n```\n\nMulti-step jobs with automatic retries, state persistence, resume from failure\n\n## See Also\n\n- [API](./api.md) - Runtime APIs\n- [Gotchas](./gotchas.md) - Common issues\n- [Configuration](./configuration.md) - Setup\n- [Frameworks](./frameworks.md) - Hono, routing, validation\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-ai/README.md", "content": "# Cloudflare Workers AI\n\nExpert guidance for Cloudflare Workers AI - serverless GPU-powered AI inference at the edge.\n\n## Overview\n\nWorkers AI provides:\n- 50+ pre-trained models (LLMs, embeddings, image generation, speech-to-text, translation)\n- Native Workers binding (no external API calls)\n- Pay-per-use pricing (neurons consumed per inference)\n- OpenAI-compatible REST API\n- Streaming support for text generation\n- Function calling with compatible models\n\n**Architecture**: Inference runs on Cloudflare's GPU network. Models load on first request (cold start 1-3s), subsequent requests are faster.\n\n## Quick Start\n\n```typescript\ninterface Env {\n AI: Ai;\n}\n\nexport default {\n async fetch(request: Request, env: Env) {\n const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [{ role: 'user', content: 'What is Cloudflare?' }]\n });\n return Response.json(response);\n }\n};\n```\n\n```bash\n# Setup - add binding to wrangler.jsonc\nwrangler dev --remote # Must use --remote for AI\nwrangler deploy\n```\n\n## Model Selection Decision Tree\n\n### Text Generation (Chat/Completion)\n\n**Quality Priority**:\n- **Best quality**: `@cf/meta/llama-3.1-70b-instruct` (expensive, ~2000 neurons)\n- **Balanced**: `@cf/meta/llama-3.1-8b-instruct` (good quality, ~200 neurons)\n- **Fastest/cheapest**: `@cf/mistral/mistral-7b-instruct-v0.1` (~50 neurons)\n\n**Function Calling**:\n- Use `@cf/meta/llama-3.1-8b-instruct` or `@cf/meta/llama-3.1-70b-instruct` (native tool support)\n\n**Code Generation**:\n- Use `@cf/deepseek-ai/deepseek-coder-6.7b-instruct` (specialized for code)\n\n### Embeddings (Semantic Search/RAG)\n\n**English text**:\n- **Best**: `@cf/baai/bge-large-en-v1.5` (1024 dims, highest quality)\n- **Balanced**: `@cf/baai/bge-base-en-v1.5` (768 dims, good quality)\n- **Fast**: `@cf/baai/bge-small-en-v1.5` (384 dims, lower quality but fast)\n\n**Multilingual**:\n- Use `@hf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2`\n\n### Image Generation\n\n- **Stable Diffusion**: `@cf/stabilityai/stable-diffusion-xl-base-1.0` (~10,000 neurons)\n- **Portraits**: `@cf/lykon/dreamshaper-8-lcm` (optimized for faces)\n\n### Other Tasks\n\n- **Speech-to-text**: `@cf/openai/whisper`\n- **Translation**: `@cf/meta/m2m100-1.2b` (100 languages)\n- **Image classification**: `@cf/microsoft/resnet-50`\n\n## SDK Approach Decision Tree\n\n### Native Binding (Recommended)\n\n**When**: Building Workers/Pages with TypeScript \n**Why**: Zero external dependencies, best performance, native types\n\n```typescript\nawait env.AI.run(model, input);\n```\n\n### REST API\n\n**When**: External services, non-Workers environments, testing \n**Why**: Standard HTTP, works anywhere\n\n```bash\ncurl https://api.cloudflare.com/client/v4/accounts//ai/run/@cf/meta/llama-3.1-8b-instruct \\\n -H \"Authorization: Bearer \" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'\n```\n\n### Vercel AI SDK Integration\n\n**When**: Using Vercel AI SDK features (streaming UI, tool calling abstractions) \n**Why**: Unified interface across providers\n\n```typescript\nimport { openai } from '@ai-sdk/openai';\n\nconst model = openai('model-name', {\n baseURL: 'https://api.cloudflare.com/client/v4/accounts//ai/v1',\n headers: { Authorization: 'Bearer ' }\n});\n```\n\n## RAG vs Direct Generation\n\n### Use RAG (Vectorize + Workers AI) When:\n- Answering questions about specific documents/data\n- Need factual accuracy from known corpus\n- Context exceeds model's window (>4K tokens)\n- Building knowledge base chat\n\n### Use Direct Generation When:\n- Creative writing, brainstorming\n- General knowledge questions\n- Small context fits in prompt (<4K tokens)\n- Cost optimization (RAG adds embedding + vector search costs)\n\n## Platform Limits\n\n| Limit | Free Tier | Paid Plans |\n|-------|-----------|------------|\n| Neurons/day | 10,000 | Pay per use |\n| Rate limit | Varies by model | Higher (contact support) |\n| Context window | Model dependent (2K-8K) | Same |\n| Streaming | ✅ Supported | ✅ Supported |\n| Function calling | ✅ Supported (select models) | ✅ Supported |\n\n**Pricing**: Free 10K neurons/day, then pay per neuron consumed (varies by model)\n\n## Common Tasks\n\n```typescript\n// Streaming text generation\nconst stream = await env.AI.run(model, { messages, stream: true });\nfor await (const chunk of stream) {\n console.log(chunk.response);\n}\n\n// Embeddings for RAG\nconst { data } = await env.AI.run('@cf/baai/bge-base-en-v1.5', {\n text: ['Query text', 'Document 1', 'Document 2']\n});\n\n// Function calling\nconst response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [{ role: 'user', content: 'What is the weather?' }],\n tools: [{\n type: 'function',\n function: { name: 'getWeather', parameters: { ... } }\n }]\n});\n```\n\n## Development Workflow\n\n```bash\n# Always use --remote for AI (local doesn't have models)\nwrangler dev --remote\n\n# Deploy to production\nwrangler deploy\n\n# View model catalog\n# https://developers.cloudflare.com/workers-ai/models/\n```\n\n## Reading Order\n\n**Start here**: Quick Start above → configuration.md (setup)\n\n**Common tasks**:\n- First time setup: configuration.md → Add binding + deploy\n- Choose model: Model Selection Decision Tree (above) → api.md\n- Build RAG: patterns.md → Vectorize integration\n- Optimize costs: Model Selection + gotchas.md (rate limits)\n- Debugging: gotchas.md → Common errors\n\n## In This Reference\n\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, TypeScript types, bindings, environment variables\n- [api.md](./api.md) - env.AI.run(), streaming, function calling, REST API, response types\n- [patterns.md](./patterns.md) - RAG with Vectorize, prompt engineering, batching, error handling, caching\n- [gotchas.md](./gotchas.md) - Deprecated @cloudflare/ai package, rate limits, pricing, common errors\n\n## See Also\n\n- [vectorize](../vectorize/) - Vector database for RAG patterns\n- [ai-gateway](../ai-gateway/) - Caching, rate limiting, analytics for AI requests\n- [workers](../workers/) - Worker runtime and fetch handler patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-ai/api.md", "content": "# Workers AI API Reference\n\n## Core Method\n\n```typescript\nconst response = await env.AI.run(model, input);\n```\n\n## Text Generation\n\n```typescript\nconst result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [\n { role: 'system', content: 'You are helpful' },\n { role: 'user', content: 'Hello' }\n ],\n temperature: 0.7, // 0-1\n max_tokens: 100\n});\nconsole.log(result.response);\n```\n\n**Streaming:**\n```typescript\nconst stream = await env.AI.run(model, { messages, stream: true });\nreturn new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });\n```\n\n## Embeddings\n\n```typescript\nconst result = await env.AI.run('@cf/baai/bge-base-en-v1.5', {\n text: ['Query', 'Doc 1', 'Doc 2'] // Batch for efficiency\n});\nconst [queryEmbed, doc1Embed, doc2Embed] = result.data; // 768-dim vectors\n```\n\n## Function Calling\n\n```typescript\nconst tools = [{\n type: 'function',\n function: {\n name: 'getWeather',\n description: 'Get weather for location',\n parameters: {\n type: 'object',\n properties: { location: { type: 'string' } },\n required: ['location']\n }\n }\n}];\n\nconst response = await env.AI.run(model, { messages, tools });\nif (response.tool_calls) {\n const args = JSON.parse(response.tool_calls[0].function.arguments);\n // Execute function, send result back\n}\n```\n\n## Image Generation\n\n```typescript\nconst image = await env.AI.run('@cf/stabilityai/stable-diffusion-xl-base-1.0', {\n prompt: 'Mountain sunset',\n num_steps: 20, // 1-20\n guidance: 7.5 // 1-20\n});\nreturn new Response(image, { headers: { 'Content-Type': 'image/png' } });\n```\n\n## Speech Recognition\n\n```typescript\nconst audioArray = Array.from(new Uint8Array(await request.arrayBuffer()));\nconst result = await env.AI.run('@cf/openai/whisper', { audio: audioArray });\nconsole.log(result.text);\n```\n\n## Translation\n\n```typescript\nconst result = await env.AI.run('@cf/meta/m2m100-1.2b', {\n text: 'Hello',\n source_lang: 'en',\n target_lang: 'es'\n});\nconsole.log(result.translated_text);\n```\n\n## REST API\n\n```bash\ncurl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/meta/llama-3.1-8b-instruct \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'\n```\n\n## Error Codes\n\n| Code | Meaning | Fix |\n|------|---------|-----|\n| 7502 | Model not found | Check spelling |\n| 7504 | Validation failed | Verify input schema |\n| 7505 | Rate limited | Reduce rate or upgrade |\n| 7506 | Context exceeded | Reduce input size |\n\n## Performance Tips\n\n1. **Batch embeddings** - single request for multiple texts\n2. **Stream long responses** - reduce perceived latency\n3. **Accept cold starts** - first request ~1-3s, subsequent ~100-500ms\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-ai/configuration.md", "content": "# Workers AI Configuration\n\n## wrangler.jsonc\n\n```jsonc\n{\n \"name\": \"my-ai-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2024-01-01\",\n \"ai\": {\n \"binding\": \"AI\"\n }\n}\n```\n\n## TypeScript\n\n```bash\nnpm install --save-dev @cloudflare/workers-types\n```\n\n```typescript\ninterface Env {\n AI: Ai;\n}\n\nexport default {\n async fetch(request: Request, env: Env) {\n const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [{ role: 'user', content: 'Hello' }]\n });\n return Response.json(response);\n }\n};\n```\n\n## Local Development\n\n```bash\nwrangler dev --remote # Required for AI - no local inference\n```\n\n## REST API\n\n```typescript\nconst response = await fetch(\n `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct`,\n {\n method: 'POST',\n headers: { 'Authorization': `Bearer ${API_TOKEN}` },\n body: JSON.stringify({ messages: [{ role: 'user', content: 'Hello' }] })\n }\n);\n```\n\nCreate API token at: dash.cloudflare.com/profile/api-tokens (Workers AI - Read permission)\n\n## SDK Compatibility\n\n**OpenAI SDK:**\n```typescript\nimport OpenAI from 'openai';\nconst client = new OpenAI({\n apiKey: env.CLOUDFLARE_API_TOKEN,\n baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1`\n});\n```\n\n## Multi-Model Setup\n\n```typescript\nconst MODELS = {\n chat: '@cf/meta/llama-3.1-8b-instruct',\n embed: '@cf/baai/bge-base-en-v1.5',\n image: '@cf/stabilityai/stable-diffusion-xl-base-1.0'\n};\n```\n\n## RAG Setup (with Vectorize)\n\n```jsonc\n{\n \"ai\": { \"binding\": \"AI\" },\n \"vectorize\": {\n \"bindings\": [{ \"binding\": \"VECTORIZE\", \"index_name\": \"embeddings-index\" }]\n }\n}\n```\n\n## Troubleshooting\n\n| Error | Fix |\n|-------|-----|\n| `env.AI is undefined` | Check `ai` binding in wrangler.jsonc |\n| Local AI doesn't work | Use `wrangler dev --remote` |\n| Type 'Ai' not found | Install `@cloudflare/workers-types` |\n| @cloudflare/ai package error | Don't install - use native binding |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-ai/gotchas.md", "content": "# Workers AI Gotchas\n\n## Critical: @cloudflare/ai is DEPRECATED\n\n```typescript\n// ❌ WRONG - Don't install @cloudflare/ai\nimport Ai from '@cloudflare/ai';\n\n// ✅ CORRECT - Use native binding\nexport default {\n async fetch(request: Request, env: Env) {\n await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages: [...] });\n }\n}\n```\n\n## Development\n\n### \"AI inference doesn't work locally\"\n```bash\n# ❌ Local AI doesn't work\nwrangler dev\n# ✅ Use remote\nwrangler dev --remote\n```\n\n### \"env.AI is undefined\"\nAdd binding to wrangler.jsonc:\n```jsonc\n{ \"ai\": { \"binding\": \"AI\" } }\n```\n\n## API Responses\n\n### Embedding response shape varies\n```typescript\n// @cf/baai/bge-base-en-v1.5 returns: { data: [[0.1, 0.2, ...]] }\nconst embedding = response.data[0]; // Get first element\n```\n\n### Stream returns ReadableStream\n```typescript\nconst stream = await env.AI.run(model, { messages: [...], stream: true });\nfor await (const chunk of stream) { console.log(chunk.response); }\n```\n\n## Rate Limits & Pricing\n\n| Model Type | Neurons/Request |\n|------------|-----------------|\n| Small text (7B) | ~50-200 |\n| Large text (70B) | ~500-2000 |\n| Embeddings | ~5-20 |\n| Image gen | ~10,000+ |\n\n**Free tier**: 10,000 neurons/day\n\n```typescript\n// ❌ EXPENSIVE - 70B model\nawait env.AI.run('@cf/meta/llama-3.1-70b-instruct', ...);\n// ✅ CHEAPER - Use smallest that works\nawait env.AI.run('@cf/meta/llama-3.1-8b-instruct', ...);\n```\n\n## Model-Specific\n\n### Function calling\nOnly `@cf/meta/llama-3.1-*` and `mistral-7b-instruct-v0.2` support tools.\n\n### Empty response\nCheck context limits (2K-8K tokens). Validate input structure.\n\n### Inconsistent responses\nSet `temperature: 0` for deterministic outputs.\n\n### Cold start latency\nFirst request: 1-3s. Use AI Gateway caching for frequent prompts.\n\n## TypeScript\n\n```typescript\ninterface Env {\n AI: Ai; // From @cloudflare/workers-types\n}\n\ninterface TextGenerationResponse { response: string; }\ninterface EmbeddingResponse { data: number[][]; shape: number[]; }\n```\n\n## Common Errors\n\n### 7502: Model not found\nCheck exact model name at developers.cloudflare.com/workers-ai/models/\n\n### 7504: Input validation failed\n```typescript\n// Text gen requires messages array\nawait env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [{ role: 'user', content: 'Hello' }] // ✅\n});\n\n// Embeddings require text\nawait env.AI.run('@cf/baai/bge-base-en-v1.5', { text: 'Hello' }); // ✅\n```\n\n## Vercel AI SDK Integration\n\n```typescript\nimport { openai } from '@ai-sdk/openai';\nconst model = openai('gpt-3.5-turbo', {\n baseURL: 'https://api.cloudflare.com/client/v4/accounts//ai/v1',\n headers: { Authorization: 'Bearer ' }\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-ai/patterns.md", "content": "# Workers AI Patterns\n\n## RAG (Retrieval-Augmented Generation)\n\n```typescript\n// 1. Embed query\nconst embedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: query });\n\n// 2. Search vectors\nconst results = await env.VECTORIZE.query(embedding.data[0], {\n topK: 5, returnMetadata: true\n});\n\n// 3. Build context\nconst context = results.matches.map(m => m.metadata?.text).join('\\n\\n');\n\n// 4. Generate with context\nconst response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages: [\n { role: 'system', content: `Answer based on:\\n\\n${context}` },\n { role: 'user', content: query }\n ]\n});\n```\n\n## Streaming (SSE)\n\n```typescript\nconst stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {\n messages, stream: true\n});\n\nconst { readable, writable } = new TransformStream();\nconst writer = writable.getWriter();\n\n(async () => {\n for await (const chunk of stream) {\n await writer.write(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\\n\\n`));\n }\n await writer.write(new TextEncoder().encode('data: [DONE]\\n\\n'));\n await writer.close();\n})();\n\nreturn new Response(readable, {\n headers: { 'Content-Type': 'text/event-stream' }\n});\n```\n\n## Error Handling & Retry\n\n```typescript\nasync function runWithRetry(env, model, input, maxRetries = 3) {\n for (let attempt = 0; attempt < maxRetries; attempt++) {\n try {\n return await env.AI.run(model, input);\n } catch (error) {\n if (error.message?.includes('7505') && attempt < maxRetries - 1) {\n await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));\n continue;\n }\n throw error;\n }\n }\n}\n```\n\n## Model Fallback\n\n```typescript\ntry {\n return await env.AI.run('@cf/meta/llama-3.1-70b-instruct', { messages });\n} catch {\n return await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages });\n}\n```\n\n## Prompt Patterns\n\n```typescript\n// System prompts\nconst PROMPTS = {\n json: 'Respond with valid JSON only.',\n concise: 'Keep responses brief.',\n cot: 'Think step by step before answering.'\n};\n\n// Few-shot\nmessages: [\n { role: 'system', content: 'Extract as JSON' },\n { role: 'user', content: 'John bought 3 apples for $5' },\n { role: 'assistant', content: '{\"name\":\"John\",\"item\":\"apples\",\"qty\":3}' },\n { role: 'user', content: actualInput }\n]\n```\n\n## Parallel Execution\n\n```typescript\nconst [sentiment, summary, embedding] = await Promise.all([\n env.AI.run('@cf/mistral/mistral-7b-instruct-v0.1', { messages: sentimentPrompt }),\n env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages: summaryPrompt }),\n env.AI.run('@cf/baai/bge-base-en-v1.5', { text })\n]);\n```\n\n## Cost Optimization\n\n| Task | Model | Neurons |\n|------|-------|---------|\n| Classify | `@cf/mistral/mistral-7b-instruct-v0.1` | ~50 |\n| Chat | `@cf/meta/llama-3.1-8b-instruct` | ~200 |\n| Complex | `@cf/meta/llama-3.1-70b-instruct` | ~2000 |\n| Embed | `@cf/baai/bge-base-en-v1.5` | ~10 |\n\n```typescript\n// Batch embeddings\nconst response = await env.AI.run('@cf/baai/bge-base-en-v1.5', {\n text: textsArray // Process multiple at once\n});\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-for-platforms/README.md", "content": "# Cloudflare Workers for Platforms\n\nMulti-tenant platform with isolated customer code execution at scale.\n\n## Use Cases\n\n- Multi-tenant SaaS running customer code\n- AI-generated code execution in secure sandboxes\n- Programmable platforms with isolated compute\n- Edge functions/serverless platforms\n- Website builders with static + dynamic content\n- Unlimited app deployment at scale\n\n**NOT for general Workers** - only for Workers for Platforms architecture.\n\n## Quick Start\n\n**One-click deploy:** [Platform Starter Kit](https://github.com/cloudflare/workers-for-platforms-example) deploys complete WfP setup with dispatch namespace, dispatch worker, and user worker example.\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/workers-for-platforms-example)\n\n**Manual setup:** See [configuration.md](./configuration.md) for namespace creation and dispatch worker configuration.\n\n## Key Features\n\n- Unlimited Workers per namespace (no script limits)\n- Automatic tenant isolation\n- Custom CPU/subrequest limits per customer\n- Hostname routing (subdomains/vanity domains)\n- Egress/ingress control\n- Static assets support\n- Tags for bulk operations\n\n## Architecture\n\n**4 Components:**\n1. **Dispatch Namespace** - Container for unlimited customer Workers, automatic isolation (untrusted mode by default - no request.cf access, no shared cache)\n2. **Dynamic Dispatch Worker** - Entry point, routes requests, enforces platform logic (auth, limits, validation)\n3. **User Workers** - Customer code in isolated sandboxes, API-deployed, optional bindings (KV/D1/R2/DO)\n4. **Outbound Worker** (optional) - Intercepts external fetch, controls egress, logs subrequests (blocks TCP socket connect() API)\n\n**Request Flow:**\n```\nRequest → Dispatch Worker → Determines user Worker → env.DISPATCHER.get(\"customer\") \n→ User Worker executes (Outbound Worker for external fetch) → Response → Dispatch Worker → Client\n```\n\n## Decision Trees\n\n### When to Use Workers for Platforms\n```\nNeed to run code?\n├─ Your code only → Regular Workers\n├─ Customer/AI code → Workers for Platforms\n└─ Untrusted code in sandbox → Workers for Platforms OR Sandbox API\n```\n\n### Routing Strategy Selection\n```\nHostname routing needed?\n├─ Subdomains only (*.saas.com) → `*.saas.com/*` route + subdomain extraction\n├─ Custom domains → `*/*` wildcard + Cloudflare for SaaS + KV/metadata routing\n└─ Path-based (/customer/app) → Any route + path parsing\n```\n\n### Isolation Mode Selection\n```\nWorker mode?\n├─ Running customer code → Untrusted (default)\n├─ Need request.cf geolocation → Trusted mode\n├─ Internal platform, controlled code → Trusted mode with cache key prefixes\n└─ Maximum isolation → Untrusted + unique resources per customer\n```\n\n## In This Reference\n\n| File | Purpose | When to Read |\n|------|---------|--------------|\n| [configuration.md](./configuration.md) | Namespace setup, dispatch worker config | First-time setup, changing limits |\n| [api.md](./api.md) | User worker API, dispatch API, outbound worker | Deploying workers, SDK integration |\n| [patterns.md](./patterns.md) | Multi-tenancy, routing, egress control | Planning architecture, scaling |\n| [gotchas.md](./gotchas.md) | Limits, isolation issues, best practices | Debugging, production prep |\n\n## See Also\n- [workers](../workers/) - Core Workers runtime documentation\n- [durable-objects](../durable-objects/) - Stateful multi-tenant patterns\n- [sandbox](../sandbox/) - Alternative for untrusted code execution\n- [Reference Architecture: Programmable Platforms](https://developers.cloudflare.com/reference-architecture/diagrams/serverless/programmable-platforms/)\n- [Reference Architecture: AI Vibe Coding Platform](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-for-platforms/api.md", "content": "# API Operations\n\n## Deploy User Worker\n\n```bash\ncurl -X PUT \\\n \"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -F 'metadata={\"main_module\": \"worker.mjs\"};type=application/json' \\\n -F 'worker.mjs=@worker.mjs;type=application/javascript+module'\n```\n\n### TypeScript SDK\n```typescript\nimport Cloudflare from \"cloudflare\";\n\nconst client = new Cloudflare({ apiToken: process.env.API_TOKEN });\n\nconst scriptFile = new File([scriptContent], `${scriptName}.mjs`, {\n type: \"application/javascript+module\",\n});\n\nawait client.workersForPlatforms.dispatch.namespaces.scripts.update(\n namespace, scriptName,\n {\n account_id: accountId,\n metadata: { main_module: `${scriptName}.mjs` },\n files: [scriptFile],\n }\n);\n```\n\n## TypeScript Types\n\n```typescript\nimport type { DispatchNamespace } from '@cloudflare/workers-types';\n\ninterface DispatchNamespace {\n get(name: string, options?: Record, dispatchOptions?: DynamicDispatchOptions): Fetcher;\n}\n\ninterface DynamicDispatchOptions {\n limits?: DynamicDispatchLimits;\n outbound?: Record;\n}\n\ninterface DynamicDispatchLimits {\n cpuMs?: number; // Max CPU milliseconds\n subRequests?: number; // Max fetch() calls\n}\n\n// Usage\nconst userWorker = env.DISPATCHER.get('customer-123', {}, {\n limits: { cpuMs: 50, subRequests: 20 },\n outbound: { customerId: '123', url: request.url }\n});\n```\n\n## Deploy with Bindings\n```bash\ncurl -X PUT \".../scripts/$SCRIPT_NAME\" \\\n -F 'metadata={\n \"main_module\": \"worker.mjs\",\n \"bindings\": [\n {\"type\": \"kv_namespace\", \"name\": \"MY_KV\", \"namespace_id\": \"'$KV_ID'\"}\n ],\n \"tags\": [\"customer-123\", \"production\"],\n \"compatibility_date\": \"2026-01-01\" // Use current date for new projects\n };type=application/json' \\\n -F 'worker.mjs=@worker.mjs;type=application/javascript+module'\n```\n\n## List/Delete Workers\n\n```bash\n# List\ncurl \"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts\" \\\n -H \"Authorization: Bearer $API_TOKEN\"\n\n# Delete by name\ncurl -X DELETE \".../scripts/$SCRIPT_NAME\" -H \"Authorization: Bearer $API_TOKEN\"\n\n# Delete by tag\ncurl -X DELETE \".../scripts?tags=customer-123%3Ayes\" -H \"Authorization: Bearer $API_TOKEN\"\n```\n\n**Pagination:** SDK supports async iteration. Manual: add `?per_page=100&page=1` query params.\n\n## Static Assets\n\n**3-step process:** Create session → Upload files → Deploy Worker\n\n### 1. Create Upload Session\n```bash\ncurl -X POST \".../scripts/$SCRIPT_NAME/assets-upload-session\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -d '{\n \"manifest\": {\n \"/index.html\": {\"hash\": \"08f1dfda4574284ab3c21666d1ee8c7d4\", \"size\": 1234}\n }\n }'\n# Returns: jwt, buckets\n```\n\n**Hash:** SHA-256 truncated to first 16 bytes (32 hex characters)\n\n### 2. Upload Files\n```bash\ncurl -X POST \".../workers/assets/upload?base64=true\" \\\n -H \"Authorization: Bearer $UPLOAD_JWT\" \\\n -F '08f1dfda4574284ab3c21666d1ee8c7d4='\n# Returns: completion jwt\n```\n\n**Multiple buckets:** Upload to all returned bucket URLs (typically 2 for redundancy) using same JWT and hash.\n\n### 3. Deploy with Assets\n```bash\ncurl -X PUT \".../scripts/$SCRIPT_NAME\" \\\n -F 'metadata={\n \"main_module\": \"index.js\",\n \"assets\": {\"jwt\": \"\"},\n \"bindings\": [{\"type\": \"assets\", \"name\": \"ASSETS\"}]\n };type=application/json' \\\n -F 'index.js=export default {...};type=application/javascript+module'\n```\n\n**Asset Isolation:** Assets shared across namespace by default. For customer isolation, salt hash: `sha256(customerId + fileContents).slice(0, 32)`\n\n## Dispatch Workers\n\n### Subdomain Routing\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const userWorkerName = new URL(request.url).hostname.split(\".\")[0];\n const userWorker = env.DISPATCHER.get(userWorkerName);\n return await userWorker.fetch(request);\n },\n};\n```\n\n### Path Routing\n```typescript\nconst pathParts = new URL(request.url).pathname.split(\"/\").filter(Boolean);\nconst userWorker = env.DISPATCHER.get(pathParts[0]);\nreturn await userWorker.fetch(request);\n```\n\n### KV Routing\n```typescript\nconst hostname = new URL(request.url).hostname;\nconst userWorkerName = await env.ROUTING_KV.get(hostname);\nconst userWorker = env.DISPATCHER.get(userWorkerName);\nreturn await userWorker.fetch(request);\n```\n\n## Outbound Workers\n\nControl external fetch from user Workers:\n\n### Configure\n```typescript\nconst userWorker = env.DISPATCHER.get(\n workerName, {},\n { outbound: { customer_context: { customer_name: workerName, url: request.url } } }\n);\n```\n\n### Implement\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const customerName = env.customer_name;\n const url = new URL(request.url);\n \n // Block domains\n if ([\"malicious.com\"].some(d => url.hostname.includes(d))) {\n return new Response(\"Blocked\", { status: 403 });\n }\n \n // Inject auth\n if (url.hostname === \"api.example.com\") {\n const headers = new Headers(request.headers);\n headers.set(\"Authorization\", `Bearer ${generateJWT(customerName)}`);\n return fetch(new Request(request, { headers }));\n }\n \n return fetch(request);\n },\n};\n```\n\n**Note:** Doesn't intercept DO/mTLS fetch.\n\nSee [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-for-platforms/configuration.md", "content": "# Configuration\n\n## Dispatch Namespace Binding\n\n### wrangler.jsonc\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"dispatch_namespaces\": [{\n \"binding\": \"DISPATCHER\",\n \"namespace\": \"production\"\n }]\n}\n```\n\n## Worker Isolation Mode\n\nWorkers in a namespace run in **untrusted mode** by default for security:\n- No access to `request.cf` object\n- Isolated cache per Worker (no shared cache)\n- `caches.default` disabled\n\n### Enable Trusted Mode\n\nFor internal platforms where you control all code:\n\n```bash\ncurl -X PUT \\\n \"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE\" \\\n -H \"Authorization: Bearer $API_TOKEN\" \\\n -d '{\"name\": \"'$NAMESPACE'\", \"trusted_workers\": true}'\n```\n\n**Caveats:**\n- Workers share cache within namespace (use cache key prefixes: `customer-${id}:${key}`)\n- `request.cf` object accessible\n- Redeploy existing Workers after enabling trusted mode\n\n**When to use:** Internal platforms, A/B testing platforms, need geolocation data\n\n\n### With Outbound Worker\n```jsonc\n{\n \"dispatch_namespaces\": [{\n \"binding\": \"DISPATCHER\",\n \"namespace\": \"production\",\n \"outbound\": {\n \"service\": \"outbound-worker\",\n \"parameters\": [\"customer_context\"]\n }\n }]\n}\n```\n\n## Wrangler Commands\n\n```bash\nwrangler dispatch-namespace list\nwrangler dispatch-namespace get production\nwrangler dispatch-namespace create production\nwrangler dispatch-namespace delete staging\nwrangler dispatch-namespace rename old new\n```\n\n## Custom Limits\n\nSet CPU time and subrequest limits per invocation:\n\n```typescript\nconst userWorker = env.DISPATCHER.get(\n workerName,\n {},\n {\n limits: { \n cpuMs: 10, // Max CPU ms\n subRequests: 5 // Max fetch() calls\n }\n }\n);\n```\n\nHandle limit violations:\n```typescript\ntry {\n return await userWorker.fetch(request);\n} catch (e) {\n if (e.message.includes(\"CPU time limit\")) {\n return new Response(\"CPU limit exceeded\", { status: 429 });\n }\n throw e;\n}\n```\n\n## Static Assets\n\nDeploy HTML/CSS/images with Workers. See [api.md](./api.md#static-assets) for upload process.\n\n### Wrangler\n```jsonc\n{\n \"name\": \"customer-site\",\n \"main\": \"./src/index.js\",\n \"assets\": {\n \"directory\": \"./public\",\n \"binding\": \"ASSETS\"\n }\n}\n```\n\n```bash\nnpx wrangler deploy --name customer-site --dispatch-namespace production\n```\n\n### Dashboard Deployment\n\nAlternative to CLI:\n\n1. Upload Worker file in dashboard\n2. Add `--dispatch-namespace` flag: `wrangler deploy --dispatch-namespace production`\n3. Or configure in wrangler.jsonc under `dispatch_namespaces`\n\nSee [api.md](./api.md) for programmatic deployment via REST API or SDK.\n\n## Tags\n\nOrganize/search Workers (max 8/script):\n\n```bash\n# Set tags\ncurl -X PUT \".../tags\" -d '[\"customer-123\", \"pro\", \"production\"]'\n\n# Filter by tag\ncurl \".../scripts?tags=production%3Ayes\"\n\n# Delete by tag\ncurl -X DELETE \".../scripts?tags=customer-123%3Ayes\"\n```\n\nCommon patterns: `customer-123`, `free|pro|enterprise`, `production|staging`\n\n## Bindings\n\n**Supported binding types:** 29 total including KV, D1, R2, Durable Objects, Analytics Engine, Service, Assets, Queue, Vectorize, Hyperdrive, Workflow, AI, Browser, and more.\n\nAdd via API metadata (see [api.md](./api.md#deploy-with-bindings)):\n```json\n{\n \"bindings\": [\n {\"type\": \"kv_namespace\", \"name\": \"USER_KV\", \"namespace_id\": \"...\"},\n {\"type\": \"r2_bucket\", \"name\": \"STORAGE\", \"bucket_name\": \"...\"},\n {\"type\": \"d1\", \"name\": \"DB\", \"id\": \"...\"}\n ]\n}\n```\n\nPreserve existing bindings:\n```json\n{\n \"bindings\": [{\"type\": \"r2_bucket\", \"name\": \"STORAGE\", \"bucket_name\": \"new\"}],\n \"keep_bindings\": [\"kv_namespace\", \"d1\"] // Preserves existing bindings of these types\n}\n```\n\nFor complete binding type reference, see [bindings](../bindings/) documentation\n\nSee [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-for-platforms/gotchas.md", "content": "# Gotchas & Limits\n\n## Common Errors\n\n### \"Worker not found\"\n\n**Cause:** Attempting to get Worker that doesn't exist in namespace \n**Solution:** Catch error and return 404:\n\n```typescript\ntry {\n const userWorker = env.DISPATCHER.get(workerName);\n return userWorker.fetch(request);\n} catch (e) {\n if (e.message.startsWith(\"Worker not found\")) {\n return new Response(\"Worker not found\", { status: 404 });\n }\n throw e; // Re-throw unexpected errors\n}\n```\n\n### \"CPU time limit exceeded\"\n\n**Cause:** User Worker exceeded configured CPU time limit \n**Solution:** Track violations in Analytics Engine and return 429 response; consider adjusting limits per customer tier\n\n### \"Hostname Routing Issues\"\n\n**Cause:** DNS proxy settings causing routing problems \n**Solution:** Use `*/*` wildcard route which works regardless of proxy settings for orange-to-orange routing\n\n### \"Bindings Lost on Update\"\n\n**Cause:** Not using `keep_bindings` flag when updating Worker \n**Solution:** Use `keep_bindings: true` in API requests to preserve existing bindings during updates\n\n### \"Tag Filtering Not Working\"\n\n**Cause:** Special characters not URL encoded in tag filters \n**Solution:** URL encode tags (e.g., `tags=production%3Ayes`) and avoid special chars like `,` and `&`\n\n### \"Deploy Failures with ES Modules\"\n\n**Cause:** Incorrect upload format for ES modules \n**Solution:** Use multipart form upload, specify `main_module` in metadata, and set file type to `application/javascript+module`\n\n### \"Static Asset Upload Failed\"\n\n**Cause:** Invalid hash format, expired token, or incorrect encoding \n**Solution:** Hash must be first 16 bytes (32 hex chars) of SHA-256, upload within 1 hour of session creation, deploy within 1 hour of upload completion, and Base64 encode file contents\n\n### \"Outbound Worker Not Intercepting Calls\"\n\n**Cause:** Outbound Workers don't intercept Durable Object or mTLS binding fetch \n**Solution:** Plan egress control accordingly; not all fetch calls are intercepted\n\n### \"TCP Socket Connection Failed\"\n\n**Cause:** Outbound Worker enabled blocks `connect()` API for TCP sockets \n**Solution:** Outbound Workers only intercept `fetch()` calls; TCP socket connections unavailable when outbound configured. Remove outbound if TCP needed, or use proxy pattern.\n\n### \"API Rate Limit Exceeded\"\n\n**Cause:** Exceeded Cloudflare API rate limits (1200 requests per 5 minutes per account, 200 requests per second per IP) \n**Solution:** Implement exponential backoff:\n\n```typescript\nasync function deployWithBackoff(deploy: () => Promise, maxRetries = 3) {\n for (let i = 0; i < maxRetries; i++) {\n try {\n return await deploy();\n } catch (e) {\n if (e.status === 429 && i < maxRetries - 1) {\n await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));\n continue;\n }\n throw e;\n }\n }\n}\n```\n\n### \"Gradual Deployment Not Supported\"\n\n**Cause:** Attempted to use gradual deployments with user Workers \n**Solution:** Gradual deployments not supported for Workers in dispatch namespaces. Use all-at-once deployment with staged rollout via dispatch worker logic (feature flags, percentage-based routing).\n\n### \"Asset Session Expired\"\n\n**Cause:** Upload JWT expired (1 hour validity) or completion token expired (1 hour after upload) \n**Solution:** Complete asset upload within 1 hour of session creation, and deploy Worker within 1 hour of upload completion. For large uploads, batch files or increase upload parallelism.\n\n## Platform Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Workers per namespace | Unlimited | Unlike regular Workers (500 per account) |\n| Namespaces per account | Unlimited | Best practice: 1 production + 1 staging |\n| Max tags per Worker | 8 | For filtering and organization |\n| Worker mode | Untrusted (default) | No `request.cf` access unless trusted mode |\n| Cache isolation | Per-Worker (untrusted) | Shared in trusted mode with key prefixes |\n| Durable Object namespaces | Unlimited | No per-account limit for WfP |\n| Gradual Deployments | Not supported | All-at-once only |\n| `caches.default` | Disabled (untrusted) | Use Cache API with custom keys |\n\n## Asset Upload Limits\n\n| Limit | Value | Notes |\n|-------|-------|-------|\n| Upload session JWT validity | 1 hour | Must complete upload within this time |\n| Completion token validity | 1 hour | Must deploy within this time after upload |\n| Asset hash format | First 16 bytes SHA-256 | 32 hex characters |\n| Base64 encoding | Required | For binary files |\n\n## API Rate Limits\n\n| Limit Type | Value | Scope |\n|------------|-------|-------|\n| Client API | 1200 requests / 5 min | Per account |\n| Client API | 200 requests / sec | Per IP address |\n| GraphQL | Varies by query cost | Query complexity |\n\nSee [Cloudflare API Rate Limits](https://developers.cloudflare.com/fundamentals/api/reference/limits/) for details.\n\n## Operational Limits\n\n| Operation | Limit | Notes |\n|-----------|-------|-------|\n| CPU time (custom limits) | Up to Workers plan limit | Set per-invocation in dispatch worker |\n| Subrequests (custom limits) | Up to Workers plan limit | Set per-invocation in dispatch worker |\n| Outbound Worker subrequests | Not intercepted for DO/mTLS | Only regular fetch() calls |\n| TCP sockets with outbound | Disabled | `connect()` API unavailable |\n\nSee [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-for-platforms/patterns.md", "content": "# Multi-Tenant Patterns\n\n## Billing by Plan\n\n```typescript\ninterface Env {\n DISPATCHER: DispatchNamespace;\n CUSTOMERS_KV: KVNamespace;\n}\n\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const userWorkerName = new URL(request.url).hostname.split(\".\")[0];\n const customerPlan = await env.CUSTOMERS_KV.get(userWorkerName);\n \n const plans = {\n enterprise: { cpuMs: 50, subRequests: 50 },\n pro: { cpuMs: 20, subRequests: 20 },\n free: { cpuMs: 10, subRequests: 5 },\n };\n const limits = plans[customerPlan as keyof typeof plans] || plans.free;\n \n const userWorker = env.DISPATCHER.get(userWorkerName, {}, { limits });\n return await userWorker.fetch(request);\n },\n};\n```\n\n## Resource Isolation\n\n**Complete isolation:** Create unique resources per customer\n- KV namespace per customer\n- D1 database per customer\n- R2 bucket per customer\n\n```typescript\nconst bindings = [{\n type: \"kv_namespace\",\n name: \"USER_KV\",\n namespace_id: `customer-${customerId}-kv`\n}];\n```\n\n## Hostname Routing\n\n### Wildcard Route (Recommended)\nConfigure `*/*` route on SaaS domain → dispatch Worker\n\n**Benefits:**\n- Supports subdomains + custom vanity domains\n- No per-route limits (regular Workers limited to 100 routes)\n- Programmatic control\n- Works with any DNS proxy settings\n\n**Setup:**\n1. Cloudflare for SaaS custom hostnames\n2. Fallback origin (dummy `A 192.0.2.0` if Worker is origin)\n3. DNS CNAME to SaaS domain\n4. `*/*` route → dispatch Worker\n5. Routing logic in dispatch Worker\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n const hostname = new URL(request.url).hostname;\n const hostnameData = await env.ROUTING_KV.get(`hostname:${hostname}`, { type: \"json\" });\n \n if (!hostnameData?.workerName) {\n return new Response(\"Hostname not configured\", { status: 404 });\n }\n \n const userWorker = env.DISPATCHER.get(hostnameData.workerName);\n return await userWorker.fetch(request);\n },\n};\n```\n\n### Subdomain-Only\n1. Wildcard DNS: `*.saas.com` → origin\n2. Route: `*.saas.com/*` → dispatch Worker\n3. Extract subdomain for routing\n\n### Orange-to-Orange (O2O) Behavior\n\nWhen customers use Cloudflare and CNAME to your Workers domain:\n\n| Scenario | Behavior | Route Pattern |\n|----------|----------|---------------|\n| Customer not on Cloudflare | Standard routing | `*/*` or `*.domain.com/*` |\n| Customer on Cloudflare (proxied CNAME) | Invokes Worker at edge | `*/*` required |\n| Customer on Cloudflare (DNS-only CNAME) | Standard routing | Any route works |\n\n**Recommendation:** Always use `*/*` wildcard for consistent O2O behavior.\n\n### Custom Metadata Routing\n\nFor Cloudflare for SaaS: Store worker name in custom hostname `custom_metadata`, retrieve in dispatch worker to route requests. Requires custom hostnames as subdomains of your domain.\n\n## Observability\n\n### Logpush\n- Enable on dispatch Worker → captures all user Worker logs\n- Filter by `Outcome` or `Script Name`\n\n### Tail Workers\n- Real-time logs with custom formatting\n- Receives HTTP status, `console.log()`, exceptions, diagnostics\n\n### Analytics Engine\n```typescript\n// Track violations\nenv.ANALYTICS.writeDataPoint({\n indexes: [customerName],\n blobs: [\"cpu_limit_exceeded\"],\n});\n```\n\n### GraphQL\n```graphql\nquery {\n viewer {\n accounts(filter: {accountTag: $accountId}) {\n workersInvocationsAdaptive(filter: {dispatchNamespaceName: \"production\"}) {\n sum { requests errors cpuTime }\n }\n }\n }\n}\n```\n\n## Use Case Implementations\n\n### AI Code Execution\n```typescript\nasync function deployGeneratedCode(name: string, code: string) {\n const file = new File([code], `${name}.mjs`, { type: \"application/javascript+module\" });\n await client.workersForPlatforms.dispatch.namespaces.scripts.update(\"production\", name, {\n account_id: accountId,\n metadata: { main_module: `${name}.mjs`, tags: [name, \"ai-generated\"] },\n files: [file],\n });\n}\n\n// Short limits for untrusted code\nconst userWorker = env.DISPATCHER.get(sessionId, {}, { limits: { cpuMs: 5, subRequests: 3 } });\n```\n\n**VibeSDK:** For AI-powered code generation + deployment platforms, see [VibeSDK](https://github.com/cloudflare/vibesdk) - handles AI generation, sandbox execution, live preview, and deployment.\n\nReference: [AI Vibe Coding Platform Architecture](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)\n\n### Edge Functions Platform\n```typescript\n// Route: /customer-id/function-name\nconst [customerId, functionName] = new URL(request.url).pathname.split(\"/\").filter(Boolean);\nconst workerName = `${customerId}-${functionName}`;\nconst userWorker = env.DISPATCHER.get(workerName);\n```\n\n### Website Builder\n- Deploy static assets + Worker code\n- See [api.md](./api.md#static-assets) for full implementation\n- Salt hashes for asset isolation\n\n## Best Practices\n\n### Architecture\n- One namespace per environment (production, staging)\n- Platform logic in dispatch Worker (auth, rate limiting, validation)\n- Isolation automatic (no shared cache, untrusted mode)\n\n### Routing\n- Use `*/*` wildcard routes\n- Store mappings in KV\n- Handle missing Workers gracefully\n\n### Limits & Security\n- Set custom limits by plan\n- Track violations with Analytics Engine\n- Use outbound Workers for egress control\n- Sanitize responses\n\n### Tags\n- Tag all Workers: customer ID, plan, environment\n- Enable bulk operations\n- Filter efficiently\n\nSee [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-playground/README.md", "content": "# Cloudflare Workers Playground Skill Reference\n\n## Overview\n\nCloudflare Workers Playground is a browser-based sandbox for instantly experimenting with, testing, and deploying Cloudflare Workers without authentication or setup. This skill provides patterns, APIs, and best practices specifically for Workers Playground development.\n\n**URL:** [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)\n\n## ⚠️ Playground Constraints\n\n**Playground is NOT production-equivalent:**\n- ✅ Real Workers runtime, instant testing, shareable URLs\n- ❌ No TypeScript (JavaScript only)\n- ❌ No bindings (KV, D1, R2, Durable Objects)\n- ❌ No environment variables or secrets\n- ❌ ES modules only (no Service Worker format)\n- ⚠️ Safari broken (use Chrome/Firefox)\n\n**For production:** Use `wrangler` CLI. Playground is for rapid prototyping.\n\n## Quick Start\n\nMinimal Worker:\n\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n return new Response('Hello World');\n }\n};\n```\n\nJSON API:\n\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n const data = { message: 'Hello', timestamp: Date.now() };\n return Response.json(data);\n }\n};\n```\n\nProxy with modification:\n\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n const response = await fetch('https://example.com');\n const modified = new Response(response.body, response);\n modified.headers.set('X-Custom-Header', 'added-by-worker');\n return modified;\n }\n};\n```\n\nImport from CDN:\n\n```javascript\nimport { Hono } from 'https://esm.sh/hono@3';\n\nexport default {\n async fetch(request) {\n const app = new Hono();\n app.get('/', (c) => c.text('Hello Hono!'));\n return app.fetch(request);\n }\n};\n```\n\n## Reading Order\n\n1. **[configuration.md](configuration.md)** - Start here: playground setup, constraints, deployment\n2. **[api.md](api.md)** - Core APIs: Request, Response, ExecutionContext, fetch, Cache\n3. **[patterns.md](patterns.md)** - Common use cases: routing, proxying, A/B testing, multi-module code\n4. **[gotchas.md](gotchas.md)** - Troubleshooting: errors, browser issues, limits, best practices\n\n## In This Reference\n\n- **[configuration.md](configuration.md)** - Setup, deployment, configuration\n- **[api.md](api.md)** - API endpoints, methods, interfaces\n- **[patterns.md](patterns.md)** - Common patterns, use cases, examples\n- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations\n\n## Key Features\n\n**No Setup Required:**\n- Open URL and start coding\n- No CLI, no account, no config files\n- Code executes in real Cloudflare Workers runtime\n\n**Instant Preview:**\n- Live preview pane with browser tab or HTTP tester\n- Auto-reload on code changes\n- DevTools integration (right-click → Inspect)\n\n**Share & Deploy:**\n- Copy Link generates permanent shareable URL\n- Deploy button publishes to production in ~30 seconds\n- Get `*.workers.dev` subdomain immediately\n\n## Common Use Cases\n\n- **API development:** Test endpoints before wrangler setup\n- **Learning Workers:** Experiment with APIs without local environment\n- **Prototyping:** Quick POCs for edge logic\n- **Sharing examples:** Generate shareable links for bug reports or demos\n- **Framework testing:** Import from CDN (Hono, itty-router, etc.)\n\n## Limitations vs Production\n\n| Feature | Playground | Production (wrangler) |\n|---------|------------|----------------------|\n| Language | JavaScript only | JS + TypeScript |\n| Bindings | None | KV, D1, R2, DO, AI, etc. |\n| Environment vars | None | Full support |\n| Module format | ES only | ES + Service Worker |\n| CPU time | 10ms (Free plan) | 10ms Free / 50ms Paid |\n| Custom domains | No | Yes |\n| Analytics | No | Yes |\n\n## See Also\n\n- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)\n- [Workers Examples](https://developers.cloudflare.com/workers/examples/)\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)\n- [Workers API Reference](https://developers.cloudflare.com/workers/runtime-apis/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-playground/api.md", "content": "# Workers Playground API\n\n## Handler\n\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n // request: Request, env: {} (empty in playground), ctx: ExecutionContext\n return new Response('Hello');\n }\n};\n```\n\n## Request\n\n```javascript\nconst method = request.method; // \"GET\", \"POST\"\nconst url = new URL(request.url); // Parse URL\nconst headers = request.headers; // Headers object\nconst body = await request.json(); // Read body (consumes stream)\nconst clone = request.clone(); // Clone before reading body\n\n// Query params\nurl.searchParams.get('page'); // Single value\nurl.searchParams.getAll('tag'); // Array\n\n// Cloudflare metadata\nrequest.cf.country; // \"US\"\nrequest.cf.colo; // \"SFO\"\n```\n\n## Response\n\n```javascript\n// Text\nreturn new Response('Hello', { status: 200 });\n\n// JSON\nreturn Response.json({ data }, { status: 200, headers: {...} });\n\n// Redirect\nreturn Response.redirect('/new-path', 301);\n\n// Modify existing\nconst modified = new Response(response.body, response);\nmodified.headers.set('X-Custom', 'value');\n```\n\n## ExecutionContext\n\n```javascript\n// Background work (after response sent)\nctx.waitUntil(fetch('https://logs.example.com', { method: 'POST', body: '...' }));\nreturn new Response('OK'); // Returns immediately\n```\n\n## Fetch\n\n```javascript\nconst response = await fetch('https://api.example.com');\nconst data = await response.json();\n\n// With options\nawait fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ name: 'Alice' })\n});\n```\n\n## Cache\n\n```javascript\nconst cache = caches.default;\n\n// Check cache\nlet response = await cache.match(request);\nif (!response) {\n response = await fetch(origin);\n await cache.put(request, response.clone()); // Clone before put!\n}\nreturn response;\n```\n\n## Crypto\n\n```javascript\ncrypto.randomUUID(); // UUID v4\ncrypto.getRandomValues(new Uint8Array(16));\n\n// SHA-256 hash\nconst hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(data));\n```\n\n## Limits (Playground = Free Plan)\n\n| Resource | Limit |\n|----------|-------|\n| CPU time | 10ms |\n| Subrequests | 50 |\n| Memory | 128 MB |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-playground/configuration.md", "content": "# Configuration\n\n## Getting Started\n\nNavigate to [workers.cloudflare.com/playground](https://workers.cloudflare.com/playground)\n\n- **No account required** for testing\n- **No CLI or local setup** needed\n- Code executes in real Cloudflare Workers runtime\n- Share code via URL (never expires)\n\n## Playground Constraints\n\n⚠️ **Important Limitations**\n\n| Constraint | Playground | Production Workers |\n|------------|------------|-------------------|\n| **Module Format** | ES modules only | ES modules or Service Worker |\n| **TypeScript** | Not supported (JS only) | Supported via build step |\n| **Bindings** | Not available | KV, D1, R2, Durable Objects, etc. |\n| **wrangler.toml** | Not used | Required for config |\n| **Environment Variables** | Not available | Full support |\n| **Secrets** | Not available | Full support |\n| **Custom Domains** | Not available | Full support |\n\n**Playground is for rapid prototyping only.** For production apps, use `wrangler` CLI.\n\n## Code Editor\n\n### Syntax Requirements\n\nMust export default object with `fetch` handler:\n\n```javascript\nexport default {\n async fetch(request, env, ctx) {\n return new Response('Hello World');\n }\n};\n```\n\n**Key Points:**\n- Must use ES modules (`export default`)\n- `fetch` method receives `(request, env, ctx)`\n- Must return `Response` object\n- TypeScript not supported (use plain JavaScript)\n\n### Multi-Module Code\n\nImport from external URLs or inline modules:\n\n```javascript\n// Import from CDN\nimport { Hono } from 'https://esm.sh/hono@3';\n\n// Or paste library code and import relatively\n// (See patterns.md for multi-module examples)\n\nexport default {\n async fetch(request) {\n const app = new Hono();\n app.get('/', (c) => c.text('Hello'));\n return app.fetch(request);\n }\n};\n```\n\n## Preview Panel\n\n### Browser Tab\n\nDefault interactive preview with address bar:\n- Enter custom URL paths\n- Automatic reload on code changes\n- DevTools available (right-click → Inspect)\n\n### HTTP Test Panel\n\nSwitch to **HTTP** tab for raw HTTP testing:\n- Change HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)\n- Add/edit request headers\n- Modify request body (JSON, form data, text)\n- View response headers and body\n- Test different content types\n\nExample HTTP test:\n```\nMethod: POST\nURL: /api/users\nHeaders:\n Content-Type: application/json\n Authorization: Bearer token123\nBody:\n{\n \"name\": \"Alice\",\n \"email\": \"alice@example.com\"\n}\n```\n\n## Sharing Code\n\n**Copy Link** button generates shareable URL:\n- Code embedded in URL fragment\n- Links never expire\n- No account required\n- Can be bookmarked for later\n\nExample: `https://workers.cloudflare.com/playground#abc123...`\n\n## Deploying from Playground\n\nClick **Deploy** button to move code to production:\n\n1. **Log in** to Cloudflare account (creates free account if needed)\n2. **Review** Worker name and code\n3. **Deploy** to global network (takes ~30 seconds)\n4. **Get URL**: Deployed to `.workers.dev` subdomain\n5. **Manage** from dashboard: add bindings, custom domains, analytics\n\n**After deploy:**\n- Code runs on Cloudflare's global network (300+ cities)\n- Can add KV, D1, R2, Durable Objects bindings\n- Configure custom domains and routes\n- View analytics and logs\n- Set environment variables and secrets\n\n**Note:** Deployed Workers are production-ready but start on Free plan (100k requests/day).\n\n## Browser Compatibility\n\n| Browser | Status | Notes |\n|---------|--------|-------|\n| Chrome/Edge | ✅ Full support | Recommended |\n| Firefox | ✅ Full support | Works well |\n| Safari | ⚠️ Broken | Preview fails with \"PreviewRequestFailed\" |\n\n**Safari users:** Use Chrome, Firefox, or Edge for Workers Playground.\n\n## DevTools Integration\n\n1. **Open preview** in browser tab\n2. **Right-click** → Inspect Element\n3. **Console tab** shows Worker logs:\n - `console.log()` output\n - Uncaught errors\n - Network requests (subrequests)\n\n**Note:** DevTools show client-side console, not Worker execution logs. For production logging, use Logpush or Tail Workers.\n\n## Limits in Playground\n\nSame as production Free plan:\n\n| Resource | Limit | Notes |\n|----------|-------|-------|\n| CPU time | 10ms | Per request |\n| Memory | 128 MB | Per request |\n| Script size | 1 MB | After compression |\n| Subrequests | 50 | Outbound fetch calls |\n| Request size | 100 MB | Incoming |\n| Response size | Unlimited | Outgoing (streamed) |\n\n**Exceeding CPU time** throws error immediately. Optimize hot paths or upgrade to Paid plan (50ms CPU).\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-playground/gotchas.md", "content": "# Workers Playground Gotchas\n\n## Platform Limitations\n\n| Limitation | Impact | Workaround |\n|------------|--------|------------|\n| Safari broken | Preview fails | Use Chrome/Firefox/Edge |\n| TypeScript unsupported | TS syntax errors | Write plain JS or use JSDoc |\n| No bindings | `env` always `{}` | Mock data or use external APIs |\n| No env vars | Can't access secrets | Hardcode for testing |\n\n## Common Runtime Errors\n\n### \"Response body already read\"\n\n```javascript\n// ❌ Body consumed twice\nconst body = await request.text();\nawait fetch(url, { body: request.body }); // Error!\n\n// ✅ Clone first\nconst clone = request.clone();\nconst body = await request.text();\nawait fetch(url, { body: clone.body });\n```\n\n### \"Worker exceeded CPU time\"\n\n**Limit:** 10ms (free), 50ms (paid)\n\n```javascript\n// ✅ Move slow work to background\nctx.waitUntil(fetch('https://analytics.example.com', {...}));\nreturn new Response('OK'); // Return immediately\n```\n\n### \"Too many subrequests\"\n\n**Limit:** 50 (free), 1000 (paid)\n\n```javascript\n// ❌ 100 individual fetches\n// ✅ Batch into single API call\nawait fetch('https://api.example.com/batch', {\n body: JSON.stringify({ ids: [...] })\n});\n```\n\n## Best Practices\n\n```javascript\n// Clone before caching\nawait cache.put(request, response.clone());\nreturn response;\n\n// Validate input early\nif (request.method !== 'POST') return new Response('', { status: 405 });\n\n// Handle errors\ntry { ... } catch (e) {\n return Response.json({ error: e.message }, { status: 500 });\n}\n```\n\n## Limits\n\n| Resource | Free | Paid |\n|----------|------|------|\n| CPU time | 10ms | 50ms |\n| Memory | 128 MB | 128 MB |\n| Subrequests | 50 | 1000 |\n\n## Browser Support\n\n| Browser | Status |\n|---------|--------|\n| Chrome | ✅ Recommended |\n| Firefox | ✅ Works |\n| Edge | ✅ Works |\n| Safari | ❌ Broken |\n\n## Debugging\n\n```javascript\nconsole.log('URL:', request.url); // View in browser DevTools Console\n```\n\n**Note:** `console.log` works in playground. For production, use Logpush or Tail Workers.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-playground/patterns.md", "content": "# Workers Playground Patterns\n\n## JSON API\n\n```javascript\nexport default {\n async fetch(request) {\n const url = new URL(request.url);\n if (url.pathname === '/api/hello') return Response.json({ message: 'Hello' });\n if (url.pathname === '/api/echo' && request.method === 'POST') {\n return Response.json({ received: await request.json() });\n }\n return Response.json({ error: 'Not found' }, { status: 404 });\n }\n};\n```\n\n## Router Pattern\n\n```javascript\nconst routes = {\n '/': () => new Response('Home'),\n '/api/users': () => Response.json([{ id: 1, name: 'Alice' }])\n};\n\nexport default {\n async fetch(request) {\n const handler = routes[new URL(request.url).pathname];\n return handler ? handler() : new Response('Not Found', { status: 404 });\n }\n};\n```\n\n## Proxy Pattern\n\n```javascript\nexport default {\n async fetch(request) {\n const url = new URL(request.url);\n url.hostname = 'api.example.com';\n return fetch(url.toString(), {\n method: request.method, headers: request.headers, body: request.body\n });\n }\n};\n```\n\n## CORS Handling\n\n```javascript\nexport default {\n async fetch(request) {\n if (request.method === 'OPTIONS') {\n return new Response(null, {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',\n 'Access-Control-Allow-Headers': 'Content-Type, Authorization'\n }\n });\n }\n const response = await fetch('https://api.example.com', request);\n const modified = new Response(response.body, response);\n modified.headers.set('Access-Control-Allow-Origin', '*');\n return modified;\n }\n};\n```\n\n## Caching\n\n```javascript\nexport default {\n async fetch(request) {\n if (request.method !== 'GET') return fetch(request);\n const cache = caches.default;\n let response = await cache.match(request);\n if (!response) {\n response = await fetch('https://api.example.com');\n if (response.status === 200) await cache.put(request, response.clone());\n }\n return response;\n }\n};\n```\n\n## Hono Framework\n\n```javascript\nimport { Hono } from 'https://esm.sh/hono@3';\nconst app = new Hono();\napp.get('/', (c) => c.text('Hello'));\napp.get('/api/users/:id', (c) => c.json({ id: c.req.param('id') }));\napp.notFound((c) => c.json({ error: 'Not found' }, 404));\nexport default app;\n```\n\n## Authentication\n\n```javascript\nexport default {\n async fetch(request) {\n const auth = request.headers.get('Authorization');\n if (!auth?.startsWith('Bearer ')) {\n return Response.json({ error: 'Unauthorized' }, { status: 401 });\n }\n const token = auth.substring(7);\n if (token !== 'secret-token') {\n return Response.json({ error: 'Invalid token' }, { status: 403 });\n }\n return Response.json({ message: 'Authenticated' });\n }\n};\n```\n\n## Error Handling\n\n```javascript\nexport default {\n async fetch(request) {\n try {\n const response = await fetch('https://api.example.com');\n if (!response.ok) throw new Error(`API returned ${response.status}`);\n return response;\n } catch (error) {\n return Response.json({ error: error.message }, { status: 500 });\n }\n }\n};\n```\n\n**Note:** In-memory state (Maps, variables) resets on Worker cold start. Use Durable Objects or KV for persistence.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-vpc/README.md", "content": "# Workers VPC Connectivity\n\nConnect Cloudflare Workers to private networks and internal infrastructure using TCP Sockets.\n\n## Overview\n\nWorkers VPC connectivity enables outbound TCP connections from Workers to private resources in AWS, Azure, GCP, on-premises datacenters, or any private network. This is achieved through the **TCP Sockets API** (`cloudflare:sockets`), which provides low-level network access for custom protocols and services.\n\n**Key capabilities:**\n- Direct TCP connections to private IPs and hostnames\n- TLS/StartTLS support for encrypted connections\n- Integration with Cloudflare Tunnel for secure private network access\n- Full control over wire protocols (database protocols, SSH, MQTT, custom TCP)\n\n**Note:** This reference documents the TCP Sockets API. For the newer Workers VPC Services product (HTTP-only service bindings with built-in SSRF protection), refer to separate documentation when available. VPC Services is currently in beta (2025+).\n\n## Quick Decision: Which Technology?\n\nNeed private network connectivity from Workers?\n\n| Requirement | Use | Why |\n|------------|-----|-----|\n| HTTP/HTTPS APIs in private network | VPC Services (beta, separate docs) | SSRF-safe, declarative bindings |\n| PostgreSQL/MySQL databases | [Hyperdrive](../hyperdrive/) | Connection pooling, caching, optimized |\n| Custom TCP protocols (SSH, MQTT, proprietary) | **TCP Sockets (this doc)** | Full protocol control |\n| Simple HTTP with lowest latency | TCP Sockets + [Smart Placement](../smart-placement/) | Manual optimization |\n| Expose on-prem to internet (inbound) | [Cloudflare Tunnel](../tunnel/) | Not Worker-specific |\n\n## When to Use TCP Sockets\n\n**Use TCP Sockets when you need:**\n- ✅ Direct control over wire protocols (e.g., Postgres wire protocol, SSH, Redis RESP)\n- ✅ Non-HTTP protocols (MQTT, SMTP, custom binary protocols)\n- ✅ StartTLS or custom TLS negotiation\n- ✅ Streaming binary data over TCP\n\n**Don't use TCP Sockets when:**\n- ❌ You just need HTTP/HTTPS (use `fetch()` or VPC Services)\n- ❌ You need PostgreSQL/MySQL (use Hyperdrive for pooling)\n- ❌ You need WebSocket (use native Workers WebSocket)\n\n## Quick Start\n\n```typescript\nimport { connect } from 'cloudflare:sockets';\n\nexport default {\n async fetch(req: Request): Promise {\n // Connect to private service\n const socket = connect(\n { hostname: \"db.internal.company.net\", port: 5432 },\n { secureTransport: \"on\" }\n );\n\n try {\n await socket.opened; // Wait for connection\n \n const writer = socket.writable.getWriter();\n await writer.write(new TextEncoder().encode(\"QUERY\\r\\n\"));\n await writer.close();\n\n const reader = socket.readable.getReader();\n const { value } = await reader.read();\n \n return new Response(value);\n } finally {\n await socket.close();\n }\n }\n};\n```\n\n## Architecture Pattern: Workers + Tunnel\n\nMost private network connectivity combines TCP Sockets with Cloudflare Tunnel:\n\n```\n┌─────────┐ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐\n│ Worker │────▶│ TCP Socket │────▶│ Tunnel │────▶│ Private │\n│ │ │ (this API) │ │ (cloudflared)│ │ Network │\n└─────────┘ └─────────────┘ └──────────────┘ └─────────────┘\n```\n\n1. Worker opens TCP socket to Tunnel hostname\n2. Tunnel endpoint routes to private IP\n3. Response flows back through Tunnel to Worker\n\nSee [configuration.md](./configuration.md) for Tunnel setup details.\n\n## Reading Order\n\n1. **Start here (README.md)** - Overview and decision guide\n2. **[api.md](./api.md)** - Socket interface, types, methods\n3. **[configuration.md](./configuration.md)** - Wrangler setup, Tunnel integration\n4. **[patterns.md](./patterns.md)** - Real-world examples (databases, protocols, error handling)\n5. **[gotchas.md](./gotchas.md)** - Limits, blocked ports, common errors\n\n## Key Limits\n\n| Limit | Value |\n|-------|-------|\n| Max concurrent sockets per request | 6 |\n| Blocked destinations | Cloudflare IPs, localhost, port 25 |\n| Scope requirement | Must create in handler (not global) |\n\nSee [gotchas.md](./gotchas.md) for complete limits and troubleshooting.\n\n## Best Practices\n\n1. **Always close sockets** - Use try/finally blocks\n2. **Validate destinations** - Prevent SSRF by allowlisting hosts\n3. **Use Hyperdrive for databases** - Better performance than raw TCP\n4. **Prefer fetch() for HTTP** - Only use TCP when necessary\n5. **Combine with Smart Placement** - Reduce latency to private networks\n\n## Related Technologies\n\n- **[Hyperdrive](../hyperdrive/)** - PostgreSQL/MySQL with connection pooling\n- **[Cloudflare Tunnel](../tunnel/)** - Secure private network access\n- **[Smart Placement](../smart-placement/)** - Auto-locate Workers near backends\n- **VPC Services (beta)** - HTTP-only service bindings with SSRF protection (separate docs)\n\n## Reference\n\n- [TCP Sockets API Documentation](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/)\n- [Connect to databases guide](https://developers.cloudflare.com/workers/tutorials/connect-to-postgres/)\n- [Cloudflare Tunnel setup](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-vpc/api.md", "content": "# TCP Sockets API Reference\n\nComplete API reference for the Cloudflare Workers TCP Sockets API (`cloudflare:sockets`).\n\n## Core Function: `connect()`\n\n```typescript\nfunction connect(\n address: SocketAddress,\n options?: SocketOptions\n): Socket\n```\n\nCreates an outbound TCP connection to the specified address.\n\n### Parameters\n\n#### `SocketAddress`\n\n```typescript\ninterface SocketAddress {\n hostname: string; // DNS hostname or IP address\n port: number; // TCP port (1-65535, excluding blocked ports)\n}\n```\n\n| Field | Type | Description | Example |\n|-------|------|-------------|---------|\n| `hostname` | `string` | Target hostname or IP | `\"db.internal.net\"`, `\"10.0.1.50\"` |\n| `port` | `number` | TCP port number | `5432`, `443`, `22` |\n\nDNS names are resolved at connection time. IPv4, IPv6, and private IPs (10.x, 172.16.x, 192.168.x) supported.\n\n#### `SocketOptions`\n\n```typescript\ninterface SocketOptions {\n secureTransport?: \"off\" | \"on\" | \"starttls\";\n allowHalfOpen?: boolean;\n}\n```\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `secureTransport` | `\"off\" \\| \"on\" \\| \"starttls\"` | `\"off\"` | TLS mode |\n| `allowHalfOpen` | `boolean` | `false` | Allow half-closed connections |\n\n**`secureTransport` modes:**\n\n| Mode | Behavior | Use Case |\n|------|----------|----------|\n| `\"off\"` | Plain TCP, no encryption | Testing, internal trusted networks |\n| `\"on\"` | Immediate TLS handshake | HTTPS, secure databases, SSH |\n| `\"starttls\"` | Start plain, upgrade later with `startTls()` | Postgres, SMTP, IMAP |\n\n**`allowHalfOpen`:** When `false` (default), closing read stream auto-closes write stream. When `true`, streams are independent.\n\n### Returns\n\nA `Socket` object with readable/writable streams.\n\n## Socket Interface\n\n```typescript\ninterface Socket {\n // Streams\n readable: ReadableStream;\n writable: WritableStream;\n \n // Connection state\n opened: Promise;\n closed: Promise;\n \n // Methods\n close(): Promise;\n startTls(): Socket;\n}\n```\n\n### Properties\n\n#### `readable: ReadableStream`\n\nStream for reading data from the socket. Use `getReader()` to consume data.\n\n```typescript\nconst reader = socket.readable.getReader();\nconst { done, value } = await reader.read(); // Read one chunk\n```\n\n#### `writable: WritableStream`\n\nStream for writing data to the socket. Use `getWriter()` to send data.\n\n```typescript\nconst writer = socket.writable.getWriter();\nawait writer.write(new TextEncoder().encode(\"HELLO\\r\\n\"));\nawait writer.close();\n```\n\n#### `opened: Promise`\n\nPromise that resolves when connection succeeds, rejects on failure.\n\n```typescript\ninterface SocketInfo {\n remoteAddress?: string; // May be undefined\n localAddress?: string; // May be undefined\n}\n\ntry {\n const info = await socket.opened;\n} catch (error) {\n // Connection failed\n}\n```\n\n#### `closed: Promise`\n\nPromise that resolves when socket is fully closed (both directions).\n\n### Methods\n\n#### `close(): Promise`\n\nCloses the socket gracefully, waiting for pending writes to complete.\n\n```typescript\nconst socket = connect({ hostname: \"api.internal\", port: 443 });\ntry {\n // Use socket\n} finally {\n await socket.close(); // Always call in finally block\n}\n```\n\n#### `startTls(): Socket`\n\nUpgrades connection to TLS. Only available when `secureTransport: \"starttls\"` was specified.\n\n```typescript\nconst socket = connect(\n { hostname: \"db.internal\", port: 5432 },\n { secureTransport: \"starttls\" }\n);\n\n// Send protocol-specific StartTLS command\nconst writer = socket.writable.getWriter();\nawait writer.write(new TextEncoder().encode(\"STARTTLS\\r\\n\"));\n\n// Upgrade to TLS - use returned socket, not original\nconst secureSocket = socket.startTls();\nconst secureWriter = secureSocket.writable.getWriter();\n```\n\n## Complete Example\n\n```typescript\nimport { connect } from 'cloudflare:sockets';\n\nexport default {\n async fetch(req: Request): Promise {\n const socket = connect({ hostname: \"echo.example.com\", port: 7 }, { secureTransport: \"on\" });\n\n try {\n await socket.opened;\n \n const writer = socket.writable.getWriter();\n await writer.write(new TextEncoder().encode(\"Hello, TCP!\\n\"));\n await writer.close();\n\n const reader = socket.readable.getReader();\n const { value } = await reader.read();\n \n return new Response(value);\n } finally {\n await socket.close();\n }\n }\n};\n```\n\nSee [patterns.md](./patterns.md) for multi-chunk reading, error handling, and protocol implementations.\n\n## Quick Reference\n\n| Task | Code |\n|------|------|\n| Import | `import { connect } from 'cloudflare:sockets';` |\n| Connect | `connect({ hostname: \"host\", port: 443 })` |\n| With TLS | `connect(addr, { secureTransport: \"on\" })` |\n| StartTLS | `socket.startTls()` after handshake |\n| Write | `await writer.write(data); await writer.close();` |\n| Read | `const { value } = await reader.read();` |\n| Error handling | `try { await socket.opened; } catch { }` |\n| Always close | `try { } finally { await socket.close(); }` |\n\n## See Also\n\n- [patterns.md](./patterns.md) - Real-world protocol implementations\n- [configuration.md](./configuration.md) - Wrangler setup and environment variables\n- [gotchas.md](./gotchas.md) - Limits and error handling\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-vpc/configuration.md", "content": "# Configuration\n\nSetup and configuration for TCP Sockets in Cloudflare Workers.\n\n## Wrangler Configuration\n\n### Basic Setup\n\nTCP Sockets are available by default in Workers runtime. No special configuration required in `wrangler.jsonc`:\n\n```jsonc\n{\n \"name\": \"private-network-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\"\n}\n```\n\n### Environment Variables\n\nStore connection details as env vars:\n\n```jsonc\n{\n \"vars\": { \"DB_HOST\": \"10.0.1.50\", \"DB_PORT\": \"5432\" }\n}\n```\n\n```typescript\ninterface Env { DB_HOST: string; DB_PORT: string; }\n\nexport default {\n async fetch(req: Request, env: Env): Promise {\n const socket = connect({ hostname: env.DB_HOST, port: parseInt(env.DB_PORT) });\n }\n};\n```\n\n### Per-Environment Configuration\n\n```jsonc\n{\n \"vars\": { \"DB_HOST\": \"localhost\" },\n \"env\": {\n \"staging\": { \"vars\": { \"DB_HOST\": \"staging-db.internal.net\" } },\n \"production\": { \"vars\": { \"DB_HOST\": \"prod-db.internal.net\" } }\n }\n}\n```\n\nDeploy: `wrangler deploy --env staging` or `wrangler deploy --env production`\n\n## Integration with Cloudflare Tunnel\n\nTo connect Workers to private networks, combine TCP Sockets with Cloudflare Tunnel:\n\n```\nWorker (TCP Socket) → Tunnel hostname → cloudflared → Private Network\n```\n\n### Quick Setup\n\n1. **Install cloudflared** on a server inside your private network\n2. **Create tunnel**: `cloudflared tunnel create my-private-network`\n3. **Configure routing** in `config.yml`:\n\n```yaml\ntunnel: \ncredentials-file: /path/to/.json\ningress:\n - hostname: db.internal.example.com\n service: tcp://10.0.1.50:5432\n - service: http_status:404 # Required catch-all\n```\n\n4. **Run tunnel**: `cloudflared tunnel run my-private-network`\n5. **Connect from Worker**:\n\n```typescript\nconst socket = connect(\n { hostname: \"db.internal.example.com\", port: 5432 }, // Tunnel hostname\n { secureTransport: \"on\" }\n);\n```\n\nFor detailed Tunnel setup, see [Tunnel configuration reference](../tunnel/configuration.md).\n\n## Smart Placement Integration\n\nReduce latency by auto-placing Workers near backends:\n\n```jsonc\n{ \"placement\": { \"mode\": \"smart\" } }\n```\n\nWorkers automatically relocate closer to TCP socket destinations after observing connection latency. See [Smart Placement reference](../smart-placement/).\n\n## Secrets Management\n\nStore sensitive credentials as secrets (not in wrangler.jsonc):\n\n```bash\nwrangler secret put DB_PASSWORD # Enter value when prompted\n```\n\nAccess in Worker via `env.DB_PASSWORD`. Use in protocol handshake or authentication.\n\n## Local Development\n\nTest with `wrangler dev`. Note: Local mode may not access private networks. Use public endpoints or mock servers for development:\n\n```typescript\nconst config = process.env.NODE_ENV === 'dev' \n ? { hostname: 'localhost', port: 5432 } // Mock\n : { hostname: 'db.internal.example.com', port: 5432 }; // Production\n```\n\n## Connection String Patterns\n\nParse connection strings to extract host and port:\n\n```typescript\nfunction parseConnectionString(connStr: string): SocketAddress {\n const url = new URL(connStr); // e.g., \"postgres://10.0.1.50:5432/mydb\"\n return { hostname: url.hostname, port: parseInt(url.port) || 5432 };\n}\n```\n\n## Hyperdrive Integration\n\nFor PostgreSQL/MySQL, prefer Hyperdrive over raw TCP sockets (includes connection pooling):\n\n```jsonc\n{ \"hyperdrive\": [{ \"binding\": \"DB\", \"id\": \"\" }] }\n```\n\nSee [Hyperdrive reference](../hyperdrive/) for complete setup.\n\n## Compatibility\n\nTCP Sockets available in all modern Workers. Use current date: `\"compatibility_date\": \"2025-01-01\"`. No special flags required.\n\n## Related Configuration\n\n- **[Tunnel Configuration](../tunnel/configuration.md)** - Detailed cloudflared setup\n- **[Smart Placement](../smart-placement/configuration.md)** - Placement mode options\n- **[Hyperdrive](../hyperdrive/configuration.md)** - Database connection pooling setup\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-vpc/gotchas.md", "content": "# Gotchas and Troubleshooting\n\nCommon pitfalls, limitations, and solutions for TCP Sockets in Cloudflare Workers.\n\n## Platform Limits\n\n### Connection Limits\n\n| Limit | Value |\n|-------|-------|\n| Max concurrent sockets per request | 6 (hard limit) |\n| Socket lifetime | Request duration |\n| Connection timeout | Platform-dependent, no setting |\n\n**Problem:** Exceeding 6 connections throws error\n\n**Solution:** Process in batches of 6\n\n```typescript\nfor (let i = 0; i < hosts.length; i += 6) {\n const batch = hosts.slice(i, i + 6).map(h => connect({ hostname: h, port: 443 }));\n await Promise.all(batch.map(async s => { /* use */ await s.close(); }));\n}\n```\n\n### Blocked Destinations\n\nCloudflare IPs (1.1.1.1), localhost (127.0.0.1), port 25 (SMTP), Worker's own URL blocked for security.\n\n**Solution:** Use public IPs or Tunnel hostnames: `connect({ hostname: \"db.internal.company.net\", port: 5432 })`\n\n### Scope Requirements\n\n**Problem:** Sockets created in global scope fail\n\n**Cause:** Sockets tied to request lifecycle\n\n**Solution:** Create inside handler: `export default { async fetch() { const socket = connect(...); } }`\n\n## Common Errors\n\n### Error: \"proxy request failed\"\n\n**Causes:** Blocked destination (Cloudflare IP, localhost, port 25), DNS failure, network unreachable\n\n**Solution:** Validate destinations, use Tunnel hostnames, catch errors with try/catch\n\n### Error: \"TCP Loop detected\"\n\n**Cause:** Worker connecting to itself\n\n**Solution:** Connect to external service, not Worker's own hostname\n\n### Error: \"Port 25 prohibited\"\n\n**Cause:** SMTP port blocked\n\n**Solution:** Use Email Workers API for email\n\n### Error: \"socket is not open\"\n\n**Cause:** Read/write after close\n\n**Solution:** Always use try/finally to ensure proper closure order\n\n### Error: Connection timeout\n\n**Cause:** No built-in timeout\n\n**Solution:** Use `Promise.race()`:\n\n```typescript\nconst socket = connect(addr, opts);\nconst timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 5000));\nawait Promise.race([socket.opened, timeout]);\n```\n\n## TLS/SSL Issues\n\n### StartTLS Timing\n\n**Problem:** Calling `startTls()` too early\n\n**Solution:** Send protocol-specific STARTTLS command, wait for server OK, then call `socket.startTls()`\n\n### Certificate Validation\n\n**Problem:** Self-signed certs fail\n\n**Solution:** Use proper certs or Tunnel (handles TLS termination)\n\n## Performance Issues\n\n### Not Using Connection Pooling\n\n**Problem:** New connection overhead per request\n\n**Solution:** Use [Hyperdrive](../hyperdrive/) for databases (built-in pooling)\n\n### Not Using Smart Placement\n\n**Problem:** High latency to backend\n\n**Solution:** Enable: `{ \"placement\": { \"mode\": \"smart\" } }` in wrangler.jsonc\n\n### Forgetting to Close Sockets\n\n**Problem:** Resource leaks\n\n**Solution:** Always use try/finally:\n\n```typescript\nconst socket = connect({ hostname: \"api.internal\", port: 443 });\ntry {\n // Use socket\n} finally {\n await socket.close();\n}\n```\n\n## Data Handling Issues\n\n### Assuming Single Read Gets All Data\n\n**Problem:** Only reading once may miss chunked data\n\n**Solution:** Loop `reader.read()` until `done === true` (see patterns.md)\n\n### Text Encoding Issues\n\n**Problem:** Using wrong encoding\n\n**Solution:** Specify encoding: `new TextDecoder('iso-8859-1').decode(data)`\n\n## Security Issues\n\n### SSRF Vulnerability\n\n**Problem:** User-controlled destinations allow access to internal services\n\n**Solution:** Validate against strict allowlist:\n\n```typescript\nconst ALLOWED = ['api1.internal.net', 'api2.internal.net'];\nconst host = new URL(req.url).searchParams.get('host');\nif (!host || !ALLOWED.includes(host)) return new Response('Forbidden', { status: 403 });\n```\n\n## When to Use Alternatives\n\n| Use Case | Alternative | Reason |\n|----------|-------------|--------|\n| PostgreSQL/MySQL | [Hyperdrive](../hyperdrive/) | Connection pooling, caching |\n| HTTP/HTTPS | `fetch()` | Simpler, built-in |\n| HTTP with SSRF protection | VPC Services (beta 2025+) | Declarative bindings |\n\n## Debugging Tips\n\n1. **Log connection details:** `const info = await socket.opened; console.log(info.remoteAddress);`\n2. **Test with public services first:** Use tcpbin.com:4242 echo server\n3. **Verify Tunnel:** `cloudflared tunnel info ` and `cloudflared tunnel route ip list`\n\n## Related\n\n- [Hyperdrive](../hyperdrive/) - Database connections\n- [Smart Placement](../smart-placement/) - Latency optimization\n- [Tunnel Troubleshooting](../tunnel/gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workers-vpc/patterns.md", "content": "# Common Patterns\n\nReal-world patterns and examples for TCP Sockets in Cloudflare Workers.\n\n```typescript\nimport { connect } from 'cloudflare:sockets';\n```\n\n## Basic Patterns\n\n### Simple Request-Response\n\n```typescript\nconst socket = connect({ hostname: \"echo.example.com\", port: 7 }, { secureTransport: \"on\" });\ntry {\n await socket.opened;\n const writer = socket.writable.getWriter();\n await writer.write(new TextEncoder().encode(\"Hello\\n\"));\n await writer.close();\n \n const reader = socket.readable.getReader();\n const { value } = await reader.read();\n return new Response(value);\n} finally {\n await socket.close();\n}\n```\n\n### Reading All Data\n\n```typescript\nasync function readAll(socket: Socket): Promise {\n const reader = socket.readable.getReader();\n const chunks: Uint8Array[] = [];\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n chunks.push(value);\n }\n const total = chunks.reduce((sum, c) => sum + c.length, 0);\n const result = new Uint8Array(total);\n let offset = 0;\n for (const chunk of chunks) { result.set(chunk, offset); offset += chunk.length; }\n return result;\n}\n```\n\n### Streaming Response\n\n```typescript\n// Stream socket data directly to HTTP response\nconst socket = connect({ hostname: \"stream.internal\", port: 9000 }, { secureTransport: \"on\" });\nconst writer = socket.writable.getWriter();\nawait writer.write(new TextEncoder().encode(\"STREAM\\n\"));\nawait writer.close();\nreturn new Response(socket.readable);\n```\n\n## Protocol Examples\n\n### Redis RESP\n\n```typescript\n// Send: *2\\r\\n$3\\r\\nGET\\r\\n$\\r\\n\\r\\n\n// Recv: $\\r\\n\\r\\n or $-1\\r\\n for null\nconst socket = connect({ hostname: \"redis.internal\", port: 6379 });\nconst writer = socket.writable.getWriter();\nawait writer.write(new TextEncoder().encode(`*2\\r\\n$3\\r\\nGET\\r\\n$3\\r\\nkey\\r\\n`));\n```\n\n### PostgreSQL\n\n**Use [Hyperdrive](../hyperdrive/) for production.** Raw Postgres protocol is complex (startup, auth, query messages).\n\n### MQTT\n\n```typescript\nconst socket = connect({ hostname: \"mqtt.broker\", port: 1883 });\nconst writer = socket.writable.getWriter();\n// CONNECT: 0x10 0x00 0x04 \"MQTT\" 0x04 ...\n// PUBLISH: 0x30 \n```\n\n## Error Handling Patterns\n\n### Retry with Backoff\n\n```typescript\nasync function connectWithRetry(addr: SocketAddress, opts: SocketOptions, maxRetries = 3): Promise {\n for (let i = 1; i <= maxRetries; i++) {\n try {\n const socket = connect(addr, opts);\n await socket.opened;\n return socket;\n } catch (error) {\n if (i === maxRetries) throw error;\n await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i - 1))); // Exponential backoff\n }\n }\n throw new Error('Unreachable');\n}\n```\n\n### Timeout\n\n```typescript\nasync function connectWithTimeout(addr: SocketAddress, opts: SocketOptions, ms = 5000): Promise {\n const socket = connect(addr, opts);\n const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), ms));\n await Promise.race([socket.opened, timeout]);\n return socket;\n}\n```\n\n### Fallback\n\n```typescript\nasync function connectWithFallback(primary: string, fallback: string, port: number): Promise {\n try {\n const socket = connect({ hostname: primary, port }, { secureTransport: \"on\" });\n await socket.opened;\n return socket;\n } catch {\n return connect({ hostname: fallback, port }, { secureTransport: \"on\" });\n }\n}\n```\n\n## Security Patterns\n\n### Destination Allowlist (Prevent SSRF)\n\n```typescript\nconst ALLOWED_HOSTS = ['db.internal.company.net', 'api.internal.company.net', /^10\\.0\\.1\\.\\d+$/];\n\nfunction isAllowed(hostname: string): boolean {\n return ALLOWED_HOSTS.some(p => p instanceof RegExp ? p.test(hostname) : p === hostname);\n}\n\nexport default {\n async fetch(req: Request): Promise {\n const target = new URL(req.url).searchParams.get('host');\n if (!target || !isAllowed(target)) return new Response('Forbidden', { status: 403 });\n const socket = connect({ hostname: target, port: 443 });\n // Use socket...\n }\n};\n```\n\n### Connection Pooling\n\n```typescript\nclass SocketPool {\n private pool = new Map();\n \n async acquire(hostname: string, port: number): Promise {\n const key = `${hostname}:${port}`;\n const sockets = this.pool.get(key) || [];\n if (sockets.length > 0) return sockets.pop()!;\n const socket = connect({ hostname, port }, { secureTransport: \"on\" });\n await socket.opened;\n return socket;\n }\n \n release(hostname: string, port: number, socket: Socket): void {\n const key = `${hostname}:${port}`;\n const sockets = this.pool.get(key) || [];\n if (sockets.length < 3) { sockets.push(socket); this.pool.set(key, sockets); }\n else socket.close();\n }\n}\n```\n\n## Multi-Protocol Gateway\n\n```typescript\ninterface Protocol { name: string; defaultPort: number; test(host: string, port: number): Promise; }\n\nconst PROTOCOLS: Record = {\n redis: {\n name: 'redis',\n defaultPort: 6379,\n async test(host, port) {\n const socket = connect({ hostname: host, port });\n try {\n const writer = socket.writable.getWriter();\n await writer.write(new TextEncoder().encode('*1\\r\\n$4\\r\\nPING\\r\\n'));\n writer.releaseLock();\n const reader = socket.readable.getReader();\n const { value } = await reader.read();\n return new TextDecoder().decode(value || new Uint8Array());\n } finally { await socket.close(); }\n }\n }\n};\n\nexport default {\n async fetch(req: Request): Promise {\n const url = new URL(req.url);\n const proto = url.pathname.slice(1); // /redis\n const host = url.searchParams.get('host');\n if (!host || !PROTOCOLS[proto]) return new Response('Invalid', { status: 400 });\n const result = await PROTOCOLS[proto].test(host, parseInt(url.searchParams.get('port') || '') || PROTOCOLS[proto].defaultPort);\n return new Response(result);\n }\n};\n```\n\n\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workflows/README.md", "content": "# Cloudflare Workflows\n\nDurable multi-step applications with automatic retries, state persistence, and long-running execution.\n\n## What It Does\n\n- Chain steps with automatic retry logic\n- Persist state between steps (minutes → weeks)\n- Handle failures without losing progress\n- Wait for external events/approvals\n- Sleep without consuming resources\n\n**Available:** Free & Paid Workers plans\n\n## Core Concepts\n\n**Workflow**: Class extending `WorkflowEntrypoint` with `run` method\n**Instance**: Single execution with unique ID & independent state\n**Steps**: Independently retriable units via `step.do()` - API calls, DB queries, AI invocations\n**State**: Persisted from step returns; step name = cache key\n\n## Quick Start\n\n```typescript\nimport { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';\n\ntype Env = { MY_WORKFLOW: Workflow; DB: D1Database };\ntype Params = { userId: string };\n\nexport class MyWorkflow extends WorkflowEntrypoint {\n async run(event: WorkflowEvent, step: WorkflowStep) {\n const user = await step.do('fetch user', async () => {\n return await this.env.DB.prepare('SELECT * FROM users WHERE id = ?')\n .bind(event.params.userId).first();\n });\n \n await step.sleep('wait 7 days', '7 days');\n \n await step.do('send reminder', async () => {\n await sendEmail(user.email, 'Reminder!');\n });\n }\n}\n```\n\n## Key Features\n\n- **Durability**: Failed steps don't re-run successful ones\n- **Retries**: Configurable backoff (constant/linear/exponential)\n- **Events**: `waitForEvent()` for webhooks/approvals (timeout: 1h → 365d)\n- **Sleep**: `sleep()` / `sleepUntil()` for scheduling (max 365d)\n- **Parallel**: `Promise.all()` for concurrent steps\n- **Idempotency**: Check-then-execute patterns\n\n## Reading Order\n\n**Getting Started:** configuration.md → api.md → patterns.md \n**Troubleshooting:** gotchas.md\n\n## In This Reference\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, step config, bindings\n- [api.md](./api.md) - Step APIs, instance management, sleep/parameters\n- [patterns.md](./patterns.md) - Common workflows, testing, orchestration\n- [gotchas.md](./gotchas.md) - Timeouts, limits, debugging strategies\n\n## See Also\n- [durable-objects](../durable-objects/) - Alternative stateful approach\n- [queues](../queues/) - Message-driven workflows\n- [workers](../workers/) - Entry point for workflow instances\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workflows/api.md", "content": "# Workflow APIs\n\n## Step APIs\n\n```typescript\n// step.do()\nconst result = await step.do('step name', async () => { /* logic */ });\nconst result = await step.do('step name', { retries, timeout }, async () => {});\n\n// step.sleep()\nawait step.sleep('description', '1 hour');\nawait step.sleep('description', 5000); // ms\n\n// step.sleepUntil()\nawait step.sleepUntil('description', Date.parse('2024-12-31'));\n\n// step.waitForEvent()\nconst data = await step.waitForEvent('wait', {event: 'webhook-type', timeout: '24h'}); // Default 24h, max 365d\ntry { const event = await step.waitForEvent('wait', { event: 'approval', timeout: '1h' }); } catch (e) { /* Timeout */ }\n```\n\n## Instance Management\n\n```typescript\n// Create single\nconst instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); // id optional, auto-generated if omitted\n\n// Create with custom retention (default: 3 days free, 30 days paid)\nconst instance = await env.MY_WORKFLOW.create({\n id: crypto.randomUUID(),\n params: { userId: 'user123' },\n retention: '30 days' // Override default retention period\n});\n\n// Batch (max 100, idempotent: skips existing IDs)\nconst instances = await env.MY_WORKFLOW.createBatch([{id: 'user1', params: {name: 'John'}}, {id: 'user2', params: {name: 'Jane'}}]);\n\n// Get & Status\nconst instance = await env.MY_WORKFLOW.get('instance-id');\nconst status = await instance.status(); // {status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'waitingForPause' | 'unknown', error?, output?}\n\n// Control\nawait instance.pause(); await instance.resume(); await instance.terminate(); await instance.restart();\n\n// Send Events\nawait instance.sendEvent({type: 'approval', payload: { approved: true }}); // Must match waitForEvent type\n```\n\n## Triggering Workflows\n\n```typescript\n// From Worker\nexport default { async fetch(req, env) { const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); return Response.json({ id: instance.id }); }};\n\n// From Queue\nexport default { async queue(batch, env) { for (const msg of batch.messages) { await env.MY_WORKFLOW.create({id: `job-${msg.id}`, params: msg.body}); } }};\n\n// From Cron\nexport default { async scheduled(event, env) { await env.CLEANUP_WORKFLOW.create({id: `cleanup-${Date.now()}`, params: { timestamp: event.scheduledTime }}); }};\n\n// From Another Workflow (non-blocking)\nexport class ParentWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n const child = await step.do('start child', async () => await this.env.CHILD_WORKFLOW.create({id: `child-${event.instanceId}`, params: {}}));\n }\n}\n```\n\n## Error Handling\n\n```typescript\nimport { NonRetryableError } from 'cloudflare:workers';\n\n// NonRetryableError\nawait step.do('validate', async () => {\n if (!event.params.paymentMethod) throw new NonRetryableError('Payment method required');\n const res = await fetch('https://api.example.com/charge', { method: 'POST' });\n if (res.status === 401) throw new NonRetryableError('Invalid credentials'); // Don't retry\n if (!res.ok) throw new Error('Retryable failure'); // Will retry\n return res.json();\n});\n\n// Catching Errors\ntry { await step.do('risky op', async () => { throw new NonRetryableError('Failed'); }); } catch (e) { await step.do('cleanup', async () => {}); }\n\n// Idempotency\nawait step.do('charge', async () => {\n const sub = await fetch(`https://api/subscriptions/${id}`).then(r => r.json());\n if (sub.charged) return sub; // Already done\n return await fetch(`https://api/subscriptions/${id}`, {method: 'POST', body: JSON.stringify({ amount: 10.0 })}).then(r => r.json());\n});\n```\n\n## Type Constraints\n\nParams and step returns must be `Rpc.Serializable`:\n\n```typescript\n// ✅ Valid types\ntype ValidParams = {\n userId: string;\n count: number;\n tags: string[];\n metadata: Record;\n};\n\n// ❌ Invalid types\ntype InvalidParams = {\n callback: () => void; // Functions not serializable\n symbol: symbol; // Symbols not serializable\n circular: any; // Circular references not allowed\n};\n\n// Step returns follow same rules\nconst result = await step.do('fetch', async () => {\n return { userId: '123', data: [1, 2, 3] }; // ✅ Plain object\n});\n```\n\n## Sleep & Scheduling\n\n```typescript\n// Relative\nawait step.sleep('wait 1 hour', '1 hour');\nawait step.sleep('wait 30 days', '30 days');\nawait step.sleep('wait 5s', 5000); // ms\n\n// Absolute\nawait step.sleepUntil('launch date', Date.parse('24 Oct 2024 13:00:00 UTC'));\nawait step.sleepUntil('deadline', new Date('2024-12-31T23:59:59Z'));\n```\n\nUnits: second, minute, hour, day, week, month, year. Max: 365 days.\nSleeping instances don't count toward concurrency.\n\n## Parameters\n\n**Pass from Worker:**\n```typescript\nconst instance = await env.MY_WORKFLOW.create({\n id: crypto.randomUUID(),\n params: { userId: 'user123', email: 'user@example.com' }\n});\n```\n\n**Access in Workflow:**\n```typescript\nasync run(event: WorkflowEvent, step: WorkflowStep) {\n const userId = event.params.userId;\n const instanceId = event.instanceId;\n const createdAt = event.timestamp;\n}\n```\n\n**CLI Trigger:**\n```bash\nnpx wrangler workflows trigger my-workflow '{\"userId\":\"user123\"}'\n```\n\n## Wrangler CLI\n\n```bash\nnpm create cloudflare@latest my-workflow -- --template \"cloudflare/workflows-starter\"\nnpx wrangler deploy\nnpx wrangler workflows list\nnpx wrangler workflows trigger my-workflow '{\"userId\":\"user123\"}'\nnpx wrangler workflows instances list my-workflow\nnpx wrangler workflows instances describe my-workflow instance-id\nnpx wrangler workflows instances pause/resume/terminate my-workflow instance-id\n```\n\n## REST API\n\n```bash\n# Create\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances\" -H \"Authorization: Bearer {token}\" -d '{\"id\":\"custom-id\",\"params\":{\"userId\":\"user123\"}}'\n\n# Status\ncurl \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status\" -H \"Authorization: Bearer {token}\"\n\n# Send Event\ncurl -X POST \"https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events\" -H \"Authorization: Bearer {token}\" -d '{\"type\":\"approval\",\"payload\":{\"approved\":true}}'\n```\n\nSee: [configuration.md](./configuration.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workflows/configuration.md", "content": "# Workflow Configuration\n\n## wrangler.jsonc Setup\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date for new projects\n \"observability\": {\n \"enabled\": true // Enables Workflows dashboard + structured logs\n },\n \"workflows\": [\n {\n \"name\": \"my-workflow\", // Workflow name\n \"binding\": \"MY_WORKFLOW\", // Env binding\n \"class_name\": \"MyWorkflow\" // TS class name\n // \"script_name\": \"other-worker\" // For cross-script calls\n }\n ],\n \"limits\": {\n \"cpu_ms\": 300000 // 5 min max (default 30s)\n }\n}\n```\n\n## Step Configuration\n\n```typescript\n// Basic step\nconst data = await step.do('step name', async () => ({ result: 'value' }));\n\n// With retry config\nawait step.do('api call', {\n retries: {\n limit: 10, // Default: 5, or Infinity\n delay: '10 seconds', // Default: 10000ms\n backoff: 'exponential' // constant | linear | exponential\n },\n timeout: '30 minutes' // Per-attempt timeout (default: 10min)\n}, async () => {\n const res = await fetch('https://api.example.com/data');\n if (!res.ok) throw new Error('Failed');\n return res.json();\n});\n```\n\n### Parallel Steps\n```typescript\nconst [user, settings] = await Promise.all([\n step.do('fetch user', async () => this.env.KV.get(`user:${id}`)),\n step.do('fetch settings', async () => this.env.KV.get(`settings:${id}`))\n]);\n```\n\n### Conditional Steps\n```typescript\nconst config = await step.do('fetch config', async () => \n this.env.KV.get('flags', { type: 'json' })\n);\n\n// ✅ Deterministic (based on step output)\nif (config.enableEmail) {\n await step.do('send email', async () => sendEmail());\n}\n\n// ❌ Non-deterministic (Date.now outside step)\nif (Date.now() > deadline) { /* BAD */ }\n```\n\n### Dynamic Steps (Loops)\n```typescript\nconst files = await step.do('list files', async () => \n this.env.BUCKET.list()\n);\n\nfor (const file of files.objects) {\n await step.do(`process ${file.key}`, async () => {\n const obj = await this.env.BUCKET.get(file.key);\n return processData(await obj.arrayBuffer());\n });\n}\n```\n\n## Multiple Workflows\n\n```jsonc\n{\n \"workflows\": [\n {\"name\": \"user-onboarding\", \"binding\": \"USER_ONBOARDING\", \"class_name\": \"UserOnboarding\"},\n {\"name\": \"data-processing\", \"binding\": \"DATA_PROCESSING\", \"class_name\": \"DataProcessing\"}\n ]\n}\n```\n\nEach class extends `WorkflowEntrypoint` with its own `Params` type.\n\n## Cross-Script Bindings\n\nWorker A defines workflow. Worker B calls it by adding `script_name`:\n\n```jsonc\n// Worker B (caller)\n{\n \"workflows\": [{\n \"name\": \"billing-workflow\",\n \"binding\": \"BILLING\",\n \"script_name\": \"billing-worker\" // Points to Worker A\n }]\n}\n```\n\n## Bindings\n\nWorkflows access Cloudflare bindings via `this.env`:\n\n```typescript\ntype Env = {\n MY_WORKFLOW: Workflow;\n KV: KVNamespace;\n DB: D1Database;\n BUCKET: R2Bucket;\n AI: Ai;\n VECTORIZE: VectorizeIndex;\n};\n\nawait step.do('use bindings', async () => {\n const kv = await this.env.KV.get('key');\n const db = await this.env.DB.prepare('SELECT * FROM users').first();\n const file = await this.env.BUCKET.get('file.txt');\n const ai = await this.env.AI.run('@cf/meta/llama-2-7b-chat-int8', { prompt: 'Hi' });\n});\n```\n\n## Pages Functions Binding\n\nPages Functions can trigger Workflows via service bindings:\n\n```typescript\n// functions/_middleware.ts\nexport const onRequest: PagesFunction = async ({ env, request }) => {\n const instance = await env.MY_WORKFLOW.create({\n params: { url: request.url }\n });\n return new Response(`Started ${instance.id}`);\n};\n```\n\nConfigure in wrangler.jsonc under `service_bindings`.\n\nSee: [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workflows/gotchas.md", "content": "# Gotchas & Debugging\n\n## Common Errors\n\n### \"Step Timeout\"\n\n**Cause:** Step execution exceeding 10 minute default timeout or configured timeout \n**Solution:** Set custom timeout with `step.do('long operation', {timeout: '30 minutes'}, async () => {...})` or increase CPU limit in wrangler.jsonc (max 5min CPU time)\n\n### \"waitForEvent Timeout\"\n\n**Cause:** Event not received within timeout period (default 24h, max 365d) \n**Solution:** Wrap in try-catch to handle timeout gracefully and proceed with default behavior\n\n### \"Non-Deterministic Step Names\"\n\n**Cause:** Using dynamic values like `Date.now()` in step names causes replay issues \n**Solution:** Use deterministic values like `event.instanceId` for step names\n\n### \"State Lost in Variables\"\n\n**Cause:** Using module-level or local variables to store state which is lost on hibernation \n**Solution:** Return values from `step.do()` which are automatically persisted: `const total = await step.do('step 1', async () => 10)`\n\n### \"Non-Deterministic Conditionals\"\n\n**Cause:** Using non-deterministic logic (like `Date.now()`) outside steps in conditionals \n**Solution:** Move non-deterministic operations inside steps: `const isLate = await step.do('check', async () => Date.now() > deadline)`\n\n### \"Large Step Returns Exceeding Limit\"\n\n**Cause:** Returning data >1 MiB from step \n**Solution:** Store large data in R2 and return only reference: `{ key: 'r2-object-key' }`\n\n### \"Step Exceeded CPU Limit But Ran for < 30s\"\n\n**Cause:** Confusion between CPU time (active compute) and wall-clock time (includes I/O waits) \n**Solution:** Network requests, database queries, and sleeps don't count toward CPU. 30s limit = 30s of active processing\n\n### \"Idempotency Violation\"\n\n**Cause:** Step operations not idempotent, causing duplicate charges or actions on retry \n**Solution:** Check if operation already completed before executing (e.g., check if customer already charged)\n\n### \"Instance ID Collision\"\n\n**Cause:** Reusing instance IDs causing conflicts \n**Solution:** Use unique IDs with timestamp: `await env.MY_WORKFLOW.create({ id: \\`${userId}-${Date.now()}\\`, params: {} })`\n\n### \"Instance Data Disappeared After Completion\"\n\n**Cause:** Completed/errored instances are automatically deleted after retention period (3 days free / 30 days paid) \n**Solution:** Export critical data to KV/R2/D1 before workflow completes\n\n### \"Missing await on step.do\"\n\n**Cause:** Forgetting to await step.do() causing fire-and-forget behavior \n**Solution:** Always await step operations: `await step.do('task', ...)`\n\n## Limits\n\n| Limit | Free | Paid | Notes |\n|-------|------|------|-------|\n| CPU per step | 10ms | 30s (default), 5min (max) | Set via `limits.cpu_ms` in wrangler.jsonc |\n| Step state | 1 MiB | 1 MiB | Per step return value |\n| Instance state | 100 MB | 1 GB | Total state per workflow instance |\n| Steps per workflow | 1,024 | 1,024 | `step.sleep()` doesn't count |\n| Executions per day | 100k | Unlimited | Daily execution limit |\n| Concurrent instances | 25 | 10k | Maximum concurrent workflows; waiting state excluded |\n| Queued instances | 100k | 1M | Maximum queued workflow instances |\n| Subrequests per step | 50 | 1,000 | Maximum outbound requests per step |\n| State retention | 3 days | 30 days | How long completed instances kept |\n| Step timeout default | 10 min | 10 min | Per attempt |\n| waitForEvent timeout default | 24h | 24h | Maximum 365 days |\n| waitForEvent timeout max | 365 days | 365 days | Maximum wait time |\n\n**Note:** Instances in `waiting` state (from `step.sleep` or `step.waitForEvent`) don't count toward concurrent instance limit, allowing millions of sleeping workflows.\n\n## Pricing\n\n| Metric | Free | Paid | Notes |\n|--------|------|------|-------|\n| Requests | 100k/day | 10M/mo + $0.30/M | Workflow invocations |\n| CPU time | 10ms/invoke | 30M CPU-ms/mo + $0.02/M CPU-ms | Actual CPU usage |\n| Storage | 1 GB | 1 GB/mo + $0.20/GB-mo | All instances (running/errored/sleeping/completed) |\n\n## References\n\n- [Official Docs](https://developers.cloudflare.com/workflows/)\n- [Get Started Guide](https://developers.cloudflare.com/workflows/get-started/guide/)\n- [Workers API](https://developers.cloudflare.com/workflows/build/workers-api/)\n- [REST API](https://developers.cloudflare.com/api/resources/workflows/)\n- [Examples](https://developers.cloudflare.com/workflows/examples/)\n- [Limits](https://developers.cloudflare.com/workflows/reference/limits/)\n- [Pricing](https://developers.cloudflare.com/workflows/reference/pricing/)\n\nSee: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/workflows/patterns.md", "content": "# Workflow Patterns\n\n## Image Processing Pipeline\n\n```typescript\nexport class ImageProcessingWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n const imageData = await step.do('fetch', async () => (await this.env.BUCKET.get(event.params.imageKey)).arrayBuffer());\n const description = await step.do('generate description', async () => \n await this.env.AI.run('@cf/llava-hf/llava-1.5-7b-hf', {image: Array.from(new Uint8Array(imageData)), prompt: 'Describe this image', max_tokens: 50})\n );\n await step.waitForEvent('await approval', { event: 'approved', timeout: '24h' });\n await step.do('publish', async () => await this.env.BUCKET.put(`public/${event.params.imageKey}`, imageData));\n }\n}\n```\n\n## User Lifecycle\n\n```typescript\nexport class UserLifecycleWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n await step.do('welcome email', async () => await sendEmail(event.params.email, 'Welcome!'));\n await step.sleep('trial period', '7 days');\n const hasConverted = await step.do('check conversion', async () => {\n const user = await this.env.DB.prepare('SELECT subscription_status FROM users WHERE id = ?').bind(event.params.userId).first();\n return user.subscription_status === 'active';\n });\n if (!hasConverted) await step.do('trial expiration email', async () => await sendEmail(event.params.email, 'Trial ending'));\n }\n}\n```\n\n## Data Pipeline\n\n```typescript\nexport class DataPipelineWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n const rawData = await step.do('extract', {retries: { limit: 10, delay: '30s', backoff: 'exponential' }}, async () => {\n const res = await fetch(event.params.sourceUrl);\n if (!res.ok) throw new Error('Fetch failed');\n return res.json();\n });\n const transformed = await step.do('transform', async () => \n rawData.map(item => ({ id: item.id, normalized: normalizeData(item) }))\n );\n const dataRef = await step.do('store', async () => {\n const key = `processed/${Date.now()}.json`;\n await this.env.BUCKET.put(key, JSON.stringify(transformed));\n return { key };\n });\n await step.do('load', async () => {\n const data = await (await this.env.BUCKET.get(dataRef.key)).json();\n for (let i = 0; i < data.length; i += 100) {\n await this.env.DB.batch(data.slice(i, i + 100).map(item => \n this.env.DB.prepare('INSERT INTO records VALUES (?, ?)').bind(item.id, item.normalized)\n ));\n }\n });\n }\n}\n```\n\n## Human-in-the-Loop Approval\n\n```typescript\nexport class ApprovalWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n await step.do('create approval', async () => await this.env.DB.prepare('INSERT INTO approvals (id, user_id, status) VALUES (?, ?, ?)').bind(event.instanceId, event.params.userId, 'pending').run());\n try {\n const approval = await step.waitForEvent<{ approved: boolean }>('wait for approval', { event: 'approval-response', timeout: '48h' });\n if (approval.approved) { await step.do('process approval', async () => {}); } \n else { await step.do('handle rejection', async () => {}); }\n } catch (e) {\n await step.do('auto reject', async () => await this.env.DB.prepare('UPDATE approvals SET status = ? WHERE id = ?').bind('auto-rejected', event.instanceId).run());\n }\n }\n}\n```\n\n## Testing Workflows\n\n### Setup\n\n```typescript\n// vitest.config.ts\nimport { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';\n\nexport default defineWorkersConfig({\n test: {\n poolOptions: {\n workers: {\n wrangler: { configPath: './wrangler.jsonc' }\n }\n }\n }\n});\n```\n\n### Introspection API\n\n```typescript\nimport { introspectWorkflowInstance } from 'cloudflare:test';\n\nconst instance = await env.MY_WORKFLOW.create({ params: { userId: '123' } });\nconst introspector = await introspectWorkflowInstance(env.MY_WORKFLOW, instance.id);\n\n// Wait for step completion\nconst result = await introspector.waitForStepResult({ name: 'fetch user', index: 0 });\n\n// Mock step behavior\nawait introspector.modify(async (m) => {\n await m.mockStepResult({ name: 'api call' }, { mocked: true });\n});\n```\n\n## Best Practices\n\n### ✅ DO\n\n1. **Granular steps**: One API call per step (unless proving idempotency)\n2. **Idempotency**: Check-then-execute; use idempotency keys\n3. **Deterministic names**: Use static or step-output-based names\n4. **Return state**: Persist via step returns, not variables\n5. **Always await**: `await step.do()`, avoid dangling promises\n6. **Deterministic conditionals**: Base on `event.payload` or step outputs\n7. **Store large data externally**: R2/KV for >1 MiB, return refs\n8. **Batch creation**: `createBatch()` for multiple instances\n\n### ❌ DON'T\n\n1. **One giant step**: Breaks durability & retry control\n2. **State outside steps**: Lost on hibernation\n3. **Mutate events**: Events immutable, return new state\n4. **Non-deterministic logic outside steps**: `Math.random()`, `Date.now()` must be in steps\n5. **Side effects outside steps**: May duplicate on restart\n6. **Non-deterministic step names**: Prevents caching\n7. **Ignore timeouts**: `waitForEvent` throws, use try-catch\n8. **Reuse instance IDs**: Must be unique within retention\n\n## Orchestration Patterns\n\n### Fan-Out (Parallel Processing)\n```typescript\nconst files = await step.do('list', async () => this.env.BUCKET.list());\nawait Promise.all(files.objects.map((file, i) => step.do(`process ${i}`, async () => processFile(await (await this.env.BUCKET.get(file.key)).arrayBuffer()))));\n```\n\n### Parent-Child Workflows\n```typescript\nconst child = await step.do('start child', async () => await this.env.CHILD_WORKFLOW.create({id: `child-${event.instanceId}`, params: { data: result.data }}));\nawait step.do('other work', async () => console.log(`Child started: ${child.id}`));\n```\n\n### Race Pattern\n```typescript\nconst winner = await Promise.race([\n step.do('option A', async () => slowOperation()),\n step.do('option B', async () => fastOperation())\n]);\n```\n\n### Scheduled Workflow Chain\n```typescript\nexport default { async scheduled(event, env) { await env.DAILY_WORKFLOW.create({id: `daily-${event.scheduledTime}`, params: { timestamp: event.scheduledTime }}); }};\nexport class DailyWorkflow extends WorkflowEntrypoint {\n async run(event, step) {\n await step.do('daily task', async () => {});\n await step.sleep('wait 7 days', '7 days');\n await step.do('weekly followup', async () => {});\n }\n}\n```\n\nSee: [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/README.md", "content": "# Cloudflare Wrangler\n\nOfficial CLI for Cloudflare Workers - develop, manage, and deploy Workers from the command line.\n\n## What is Wrangler?\n\nWrangler is the Cloudflare Developer Platform CLI that allows you to:\n- Create, develop, and deploy Workers\n- Manage bindings (KV, D1, R2, Durable Objects, etc.)\n- Configure routing and environments\n- Run local development servers\n- Execute migrations and manage resources\n- Perform integration testing\n\n## Installation\n\n```bash\nnpm install wrangler --save-dev\n# or globally\nnpm install -g wrangler\n```\n\nRun commands: `npx wrangler ` (or `pnpm`/`yarn wrangler`)\n\n## Reading Order\n\n| If you want to... | Start here |\n|-------------------|------------|\n| Create/deploy Worker quickly | Essential Commands below → [patterns.md](./patterns.md) §New Worker |\n| Configure bindings (KV, D1, R2) | [configuration.md](./configuration.md) §Bindings |\n| Write integration tests | [api.md](./api.md) §startWorker |\n| Debug production issues | [gotchas.md](./gotchas.md) + Essential Commands §Monitoring |\n| Set up multi-environment workflow | [configuration.md](./configuration.md) §Environments |\n\n## Essential Commands\n\n### Project & Development\n```bash\nwrangler init [name] # Create new project\nwrangler dev # Local dev server (fast, simulated)\nwrangler dev --remote # Dev with remote resources (production-like)\nwrangler deploy # Deploy to production\nwrangler deploy --env staging # Deploy to environment\nwrangler versions list # List versions\nwrangler rollback [id] # Rollback deployment\nwrangler login # OAuth login\nwrangler whoami # Check auth status\n```\n\n## Resource Management\n\n### KV\n```bash\nwrangler kv namespace create NAME\nwrangler kv key put \"key\" \"value\" --namespace-id=\nwrangler kv key get \"key\" --namespace-id=\n```\n\n### D1\n```bash\nwrangler d1 create NAME\nwrangler d1 execute NAME --command \"SQL\"\nwrangler d1 migrations create NAME \"description\"\nwrangler d1 migrations apply NAME\n```\n\n### R2\n```bash\nwrangler r2 bucket create NAME\nwrangler r2 object put BUCKET/key --file path\nwrangler r2 object get BUCKET/key\n```\n\n### Other Resources\n```bash\nwrangler queues create NAME\nwrangler vectorize create NAME --dimensions N --metric cosine\nwrangler hyperdrive create NAME --connection-string \"...\"\nwrangler workflows create NAME\nwrangler constellation create NAME\nwrangler pages project create NAME\nwrangler pages deployment create --project NAME --branch main\n```\n\n### Secrets\n```bash\nwrangler secret put NAME # Set Worker secret\nwrangler secret list # List Worker secrets\nwrangler secret delete NAME # Delete Worker secret\nwrangler secret bulk FILE.json # Bulk upload from JSON\n\n# Secrets Store (centralized, reusable across Workers)\nwrangler secret-store:secret put STORE_NAME SECRET_NAME\nwrangler secret-store:secret list STORE_NAME\n```\n\n### Monitoring\n```bash\nwrangler tail # Real-time logs\nwrangler tail --env production # Tail specific env\nwrangler tail --status error # Filter by status\n```\n\n## In This Reference\n\n- [auth.md](./auth.md) - Authentication setup (`wrangler login`, API tokens)\n- [configuration.md](./configuration.md) - wrangler.jsonc setup, environments, bindings\n- [api.md](./api.md) - Programmatic API (`startWorker`, `getPlatformProxy`, events)\n- [patterns.md](./patterns.md) - Common workflows and development patterns\n- [gotchas.md](./gotchas.md) - Common pitfalls, limits, and troubleshooting\n\n## Quick Decision Tree\n\n```\nNeed to test your Worker?\n├─ Testing full Worker with bindings → api.md §startWorker\n├─ Testing individual functions → api.md §getPlatformProxy\n└─ Testing with Vitest → patterns.md §Testing with Vitest\n\nNeed to configure something?\n├─ Bindings (KV, D1, R2, etc.) → configuration.md §Bindings\n├─ Multiple environments → configuration.md §Environments\n├─ Static files → configuration.md §Workers Assets\n└─ Routing → configuration.md §Routing\n\nDevelopment not working?\n├─ Local differs from production → Use `wrangler dev --remote`\n├─ Bindings not available → gotchas.md §Binding Not Available\n└─ Auth issues → auth.md\n\nAuthentication issues?\n├─ \"Not logged in\" / \"Unauthorized\" → auth.md\n├─ First time deploying → `wrangler login` (one-time OAuth)\n└─ CI/CD setup → auth.md §API Token\n```\n\n## See Also\n\n- [workers](../workers/) - Workers runtime API reference\n- [miniflare](../miniflare/) - Local testing with Miniflare\n- [workerd](../workerd/) - Runtime that powers `wrangler dev`\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/api.md", "content": "# Wrangler Programmatic API\n\nNode.js APIs for testing and development.\n\n## startWorker (Testing)\n\nStarts Worker with real local bindings for integration tests. Stable API (replaces `unstable_startWorker`).\n\n```typescript\nimport { startWorker } from \"wrangler\";\nimport { describe, it, before, after } from \"node:test\";\nimport assert from \"node:assert\";\n\ndescribe(\"worker\", () => {\n let worker;\n \n before(async () => {\n worker = await startWorker({\n config: \"wrangler.jsonc\",\n environment: \"development\"\n });\n });\n \n after(async () => {\n await worker.dispose();\n });\n \n it(\"responds with 200\", async () => {\n const response = await worker.fetch(\"http://example.com\");\n assert.strictEqual(response.status, 200);\n });\n});\n```\n\n### Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `config` | `string` | Path to wrangler.jsonc |\n| `environment` | `string` | Environment name from config |\n| `persist` | `boolean \\| { path: string }` | Enable persistent state |\n| `bundle` | `boolean` | Enable bundling (default: true) |\n| `remote` | `false \\| true \\| \"minimal\"` | Remote mode: `false` (local), `true` (full remote), `\"minimal\"` (remote bindings only) |\n\n### Remote Mode\n\n```typescript\n// Local mode (default) - fast, simulated\nconst worker = await startWorker({ config: \"wrangler.jsonc\" });\n\n// Full remote mode - production-like, slower\nconst worker = await startWorker({ \n config: \"wrangler.jsonc\",\n remote: true \n});\n\n// Minimal remote mode - remote bindings, local Worker\nconst worker = await startWorker({ \n config: \"wrangler.jsonc\",\n remote: \"minimal\"\n});\n```\n\n## getPlatformProxy\n\nEmulate bindings in Node.js without starting Worker.\n\n```typescript\nimport { getPlatformProxy } from \"wrangler\";\n\nconst { env, dispose, caches } = await getPlatformProxy({\n configPath: \"wrangler.jsonc\",\n environment: \"production\",\n persist: { path: \".wrangler/state\" }\n});\n\n// Use bindings\nconst value = await env.MY_KV.get(\"key\");\nawait env.DB.prepare(\"SELECT * FROM users\").all();\nawait env.ASSETS.put(\"file.txt\", \"content\");\n\n// Platform APIs\nawait caches.default.put(\"https://example.com\", new Response(\"cached\"));\n\nawait dispose();\n```\n\nUse for unit tests (test functions, not full Worker) or scripts that need bindings.\n\n## Type Generation\n\nGenerate types from config: `wrangler types` → creates `worker-configuration.d.ts`\n\n## Event System\n\nListen to Worker lifecycle events for advanced workflows.\n\n```typescript\nimport { startWorker } from \"wrangler\";\n\nconst worker = await startWorker({\n config: \"wrangler.jsonc\",\n bundle: true\n});\n\n// Bundle events\nworker.on(\"bundleStart\", (details) => {\n console.log(\"Bundling started:\", details.config);\n});\n\nworker.on(\"bundleComplete\", (details) => {\n console.log(\"Bundle ready:\", details.duration);\n});\n\n// Reconfiguration events\nworker.on(\"reloadStart\", () => {\n console.log(\"Worker reloading...\");\n});\n\nworker.on(\"reloadComplete\", () => {\n console.log(\"Worker reloaded\");\n});\n\nawait worker.dispose();\n```\n\n### Dynamic Reconfiguration\n\n```typescript\nimport { startWorker } from \"wrangler\";\n\nconst worker = await startWorker({ config: \"wrangler.jsonc\" });\n\n// Replace entire config\nawait worker.setConfig({\n config: \"wrangler.staging.jsonc\",\n environment: \"staging\"\n});\n\n// Patch specific fields\nawait worker.patchConfig({\n vars: { DEBUG: \"true\" }\n});\n\nawait worker.dispose();\n```\n\n## unstable_dev (Deprecated)\n\nUse `startWorker` instead.\n\n## Multi-Worker Registry\n\nTest multiple Workers with service bindings.\n\n```typescript\nimport { startWorker } from \"wrangler\";\n\nconst auth = await startWorker({ config: \"./auth/wrangler.jsonc\" });\nconst api = await startWorker({\n config: \"./api/wrangler.jsonc\",\n bindings: { AUTH: auth } // Service binding\n});\n\nconst response = await api.fetch(\"http://example.com/api/login\");\n// API Worker calls AUTH Worker via env.AUTH.fetch()\n\nawait api.dispose();\nawait auth.dispose();\n```\n\n## Best Practices\n\n- Use `startWorker` for integration tests (tests full Worker)\n- Use `getPlatformProxy` for unit tests (tests individual functions)\n- Use `remote: true` when debugging production-specific issues\n- Use `remote: \"minimal\"` for faster tests with real bindings\n- Enable `persist: true` for debugging (state survives runs)\n- Run `wrangler types` after config changes\n- Always `dispose()` to prevent resource leaks\n- Listen to bundle events for build monitoring\n- Use multi-worker registry for testing service bindings\n\n## See Also\n\n- [README.md](./README.md) - CLI commands\n- [configuration.md](./configuration.md) - Config\n- [patterns.md](./patterns.md) - Testing patterns\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/auth.md", "content": "# Authentication\n\nAuthenticate with Cloudflare before deploying Workers or Pages.\n\n## Quick Decision Tree\n\n```\nNeed to authenticate?\n├─ Interactive/local dev → wrangler login (recommended)\n├─ CI/CD or headless → CLOUDFLARE_API_TOKEN env var\n└─ Terraform/Pulumi → See respective references\n```\n\n## wrangler login (Recommended)\n\nOne-time OAuth flow for local development:\n\n```bash\nnpx wrangler login # Opens browser, completes OAuth\nnpx wrangler whoami # Verify: shows email + account ID\n```\n\nCredentials stored locally. Works for all subsequent commands.\n\n## API Token (CI/CD)\n\nFor automated pipelines or environments without browser access:\n\n1. Go to: **https://dash.cloudflare.com/profile/api-tokens**\n2. Click **Create Token**\n3. Use template: **\"Edit Cloudflare Workers\"** (covers Workers, Pages, KV, D1, R2)\n4. Copy the token (shown only once)\n5. Set environment variable:\n\n```bash\nexport CLOUDFLARE_API_TOKEN=\"your-token-here\"\n```\n\n### Minimal Permissions by Task\n\n| Task | Template / Permissions |\n|------|------------------------|\n| Deploy Workers/Pages | \"Edit Cloudflare Workers\" template |\n| Read-only access | \"Read All Resources\" template |\n| Custom scope | Account:Read + Workers Scripts:Edit + specific resources |\n\n## Troubleshooting\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| \"Not logged in\" | No credentials | `wrangler login` or set `CLOUDFLARE_API_TOKEN` |\n| \"Authentication error\" | Invalid/expired token | Regenerate token in dashboard |\n| \"Missing account\" | Wrong account selected | `wrangler whoami` to check, add `account_id` to wrangler.jsonc |\n| Token works locally, fails CI | Token scoped to wrong account | Verify account ID matches in both places |\n| \"Insufficient permissions\" | Token lacks required scope | Create new token with correct permissions |\n\n## Verifying Authentication\n\n```bash\nnpx wrangler whoami\n```\n\nOutput shows:\n- Email (if OAuth login)\n- Account ID and name\n- Token scopes (if API token)\n\nNon-zero exit code means not authenticated.\n\n## See Also\n\n- [terraform/README.md](../terraform/README.md) - Terraform provider auth\n- [pulumi/README.md](../pulumi/README.md) - Pulumi provider auth\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/configuration.md", "content": "# Wrangler Configuration\n\nConfiguration reference for wrangler.jsonc (recommended).\n\n## Config Format\n\n**wrangler.jsonc recommended** (v3.91.0+) - provides schema validation.\n\n```jsonc\n{\n \"$schema\": \"./node_modules/wrangler/config-schema.json\",\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-01-01\", // Use current date\n \"vars\": { \"API_KEY\": \"dev-key\" },\n \"kv_namespaces\": [{ \"binding\": \"MY_KV\", \"id\": \"abc123\" }]\n}\n```\n\n## Field Inheritance\n\nInheritable: `name`, `main`, `compatibility_date`, `routes`, `triggers`\nNon-inheritable (define per env): `vars`, bindings (KV, D1, R2, etc.)\n\n## Environments\n\n```jsonc\n{\n \"name\": \"my-worker\",\n \"vars\": { \"ENV\": \"dev\" },\n \"env\": {\n \"production\": {\n \"name\": \"my-worker-prod\",\n \"vars\": { \"ENV\": \"prod\" },\n \"route\": { \"pattern\": \"example.com/*\", \"zone_name\": \"example.com\" }\n }\n }\n}\n```\n\nDeploy: `wrangler deploy --env production`\n\n## Routing\n\n```jsonc\n// Custom domain (recommended)\n{ \"routes\": [{ \"pattern\": \"api.example.com\", \"custom_domain\": true }] }\n\n// Zone-based\n{ \"routes\": [{ \"pattern\": \"api.example.com/*\", \"zone_name\": \"example.com\" }] }\n\n// workers.dev\n{ \"workers_dev\": true }\n```\n\n## Bindings\n\n```jsonc\n// Variables\n{ \"vars\": { \"API_URL\": \"https://api.example.com\" } }\n\n// KV\n{ \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"abc123\" }] }\n\n// D1\n{ \"d1_databases\": [{ \"binding\": \"DB\", \"database_id\": \"abc-123\" }] }\n\n// R2\n{ \"r2_buckets\": [{ \"binding\": \"ASSETS\", \"bucket_name\": \"my-assets\" }] }\n\n// Durable Objects\n{ \"durable_objects\": { \n \"bindings\": [{ \n \"name\": \"COUNTER\", \n \"class_name\": \"Counter\",\n \"script_name\": \"my-worker\" // Required for external DOs\n }] \n} }\n{ \"migrations\": [{ \"tag\": \"v1\", \"new_sqlite_classes\": [\"Counter\"] }] }\n\n// Service Bindings\n{ \"services\": [{ \"binding\": \"AUTH\", \"service\": \"auth-worker\" }] }\n\n// Queues\n{ \"queues\": {\n \"producers\": [{ \"binding\": \"TASKS\", \"queue\": \"task-queue\" }],\n \"consumers\": [{ \"queue\": \"task-queue\", \"max_batch_size\": 10 }]\n} }\n\n// Vectorize\n{ \"vectorize\": [{ \"binding\": \"VECTORS\", \"index_name\": \"embeddings\" }] }\n\n// Hyperdrive (requires nodejs_compat_v2 for pg/postgres)\n{ \"hyperdrive\": [{ \"binding\": \"HYPERDRIVE\", \"id\": \"hyper-id\" }] }\n{ \"compatibility_flags\": [\"nodejs_compat_v2\"] } // For pg/postgres\n\n// Workers AI\n{ \"ai\": { \"binding\": \"AI\" } }\n\n// Workflows\n{ \"workflows\": [{ \"binding\": \"WORKFLOW\", \"name\": \"my-workflow\", \"class_name\": \"MyWorkflow\" }] }\n\n// Secrets Store (centralized secrets)\n{ \"secrets_store\": [{ \"binding\": \"SECRETS\", \"id\": \"store-id\" }] }\n\n// Constellation (AI inference)\n{ \"constellation\": [{ \"binding\": \"MODEL\", \"project_id\": \"proj-id\" }] }\n```\n\n## Workers Assets (Static Files)\n\nRecommended for serving static files (replaces old `site` config).\n\n```jsonc\n{\n \"assets\": {\n \"directory\": \"./public\",\n \"binding\": \"ASSETS\",\n \"html_handling\": \"auto-trailing-slash\", // or \"none\", \"force-trailing-slash\"\n \"not_found_handling\": \"single-page-application\" // or \"404-page\", \"none\"\n }\n}\n```\n\nAccess in Worker:\n```typescript\nexport default {\n async fetch(request, env) {\n // Try serving static asset first\n const asset = await env.ASSETS.fetch(request);\n if (asset.status !== 404) return asset;\n \n // Custom logic for non-assets\n return new Response(\"API response\");\n }\n}\n```\n\n## Placement\n\nControl where Workers run geographically.\n\n```jsonc\n{\n \"placement\": {\n \"mode\": \"smart\" // or \"off\"\n }\n}\n```\n\n- `\"smart\"`: Run Worker near data sources (D1, Durable Objects) to reduce latency\n- `\"off\"`: Default distribution (run everywhere)\n\n## Auto-Provisioning (Beta)\n\nOmit resource IDs - Wrangler creates them and writes back to config on deploy.\n\n```jsonc\n{ \"kv_namespaces\": [{ \"binding\": \"MY_KV\" }] } // No id - auto-provisioned\n```\n\nAfter deploy, ID is added to config automatically.\n\n## Advanced\n\n```jsonc\n// Cron Triggers\n{ \"triggers\": { \"crons\": [\"0 0 * * *\"] } }\n\n// Observability (tracing)\n{ \"observability\": { \"enabled\": true, \"head_sampling_rate\": 0.1 } }\n\n// Runtime Limits\n{ \"limits\": { \"cpu_ms\": 100 } }\n\n// Browser Rendering\n{ \"browser\": { \"binding\": \"BROWSER\" } }\n\n// mTLS Certificates\n{ \"mtls_certificates\": [{ \"binding\": \"CERT\", \"certificate_id\": \"cert-uuid\" }] }\n\n// Logpush (stream logs to R2/S3)\n{ \"logpush\": true }\n\n// Tail Consumers (process logs with another Worker)\n{ \"tail_consumers\": [{ \"service\": \"log-worker\" }] }\n\n// Unsafe bindings (access to arbitrary bindings)\n{ \"unsafe\": { \"bindings\": [{ \"name\": \"MY_BINDING\", \"type\": \"plain_text\", \"text\": \"value\" }] } }\n```\n\n## See Also\n\n- [README.md](./README.md) - Overview and commands\n- [api.md](./api.md) - Programmatic API\n- [patterns.md](./patterns.md) - Workflows\n- [gotchas.md](./gotchas.md) - Common issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/gotchas.md", "content": "# Wrangler Common Issues\n\n## Common Errors\n\n### \"Binding ID vs name mismatch\"\n\n**Cause:** Confusion between binding name (code) and resource ID\n**Solution:** Bindings use `binding` (code name) and `id`/`database_id`/`bucket_name` (resource ID). Preview bindings need separate IDs: `preview_id`, `preview_database_id`\n\n### \"Environment not inheriting config\"\n\n**Cause:** Non-inheritable keys not redefined per environment\n**Solution:** Non-inheritable keys (bindings, vars) must be redefined per environment. Inheritable keys (routes, compatibility_date) can be overridden\n\n### \"Local dev behavior differs from production\"\n\n**Cause:** Using local simulation instead of remote execution\n**Solution:** Choose appropriate remote mode:\n- `wrangler dev` (default): Local simulation, fast, limited accuracy\n- `wrangler dev --remote`: Full remote execution, production-accurate, slower\n- Use `remote: \"minimal\"` in tests for fast tests with real remote bindings\n\n### \"startWorker doesn't match production\"\n\n**Cause:** Using local mode when remote resources needed\n**Solution:** Use `remote` option:\n```typescript\nconst worker = await startWorker({ \n config: \"wrangler.jsonc\",\n remote: true // or \"minimal\" for faster tests\n});\n```\n\n### \"Unexpected runtime changes\"\n\n**Cause:** Missing compatibility_date\n**Solution:** Always set `compatibility_date`:\n```jsonc\n{ \"compatibility_date\": \"2025-01-01\" }\n```\n\n### \"Durable Object binding not working\"\n\n**Cause:** Missing script_name for external DOs\n**Solution:** Always specify `script_name` for external Durable Objects:\n```jsonc\n{\n \"durable_objects\": {\n \"bindings\": [\n { \"name\": \"MY_DO\", \"class_name\": \"MyDO\", \"script_name\": \"my-worker\" }\n ]\n }\n}\n```\n\nFor local DOs in same Worker, `script_name` is optional.\n\n### \"Auto-provisioned resources not appearing\"\n\n**Cause:** IDs written back to config on first deploy, but config not reloaded\n**Solution:** After first deploy with auto-provisioning, config file is updated with IDs. Commit the updated config. On subsequent deploys, existing resources are reused.\n\n### \"Secrets not available in local dev\"\n\n**Cause:** Secrets set with `wrangler secret put` only work in deployed Workers\n**Solution:** For local dev, use `.dev.vars`\n\n### \"Node.js compatibility error\"\n\n**Cause:** Missing Node.js compatibility flag\n**Solution:** Some bindings (Hyperdrive with `pg`) require:\n```jsonc\n{ \"compatibility_flags\": [\"nodejs_compat_v2\"] }\n```\n\n### \"Workers Assets 404 errors\"\n\n**Cause:** Asset path mismatch or incorrect `html_handling`\n**Solution:** \n- Check `assets.directory` points to correct build output\n- Set `html_handling: \"auto-trailing-slash\"` for SPAs\n- Use `not_found_handling: \"single-page-application\"` to serve index.html for 404s\n```jsonc\n{\n \"assets\": {\n \"directory\": \"./dist\",\n \"html_handling\": \"auto-trailing-slash\",\n \"not_found_handling\": \"single-page-application\"\n }\n}\n```\n\n### \"Placement not reducing latency\"\n\n**Cause:** Misunderstanding of Smart Placement\n**Solution:** Smart Placement only helps when Worker accesses D1 or Durable Objects. It doesn't affect KV, R2, or external API latency.\n```jsonc\n{ \"placement\": { \"mode\": \"smart\" } } // Only beneficial with D1/DOs\n```\n\n### \"unstable_startWorker not found\"\n\n**Cause:** Using outdated API\n**Solution:** Use stable `startWorker` instead:\n```typescript\nimport { startWorker } from \"wrangler\"; // Not unstable_startWorker\n```\n\n### \"outboundService not mocking fetch\"\n\n**Cause:** Mock function not returning Response\n**Solution:** Always return Response, use `fetch(req)` for passthrough:\n```typescript\nconst worker = await startWorker({\n outboundService: (req) => {\n if (shouldMock(req)) {\n return new Response(\"mocked\");\n }\n return fetch(req); // Required for non-mocked requests\n }\n});\n```\n\n## Limits\n\n| Resource/Limit | Value | Notes |\n|----------------|-------|-------|\n| Bindings per Worker | 64 | Total across all types |\n| Environments | Unlimited | Named envs in config |\n| Config file size | ~1MB | Keep reasonable |\n| Workers Assets size | 25 MB | Per deployment |\n| Workers Assets files | 20,000 | Max number of files |\n| Script size (compressed) | 1 MB | Free, 10 MB paid |\n| CPU time | 10-50ms | Free, 50-500ms paid |\n| Subrequest limit | 50 | Free, 1000 paid |\n\n## Troubleshooting\n\n### Authentication Issues\n```bash\nwrangler logout\nwrangler login\nwrangler whoami\n```\n\n### Configuration Errors\n```bash\nwrangler check # Validate config\n```\nUse wrangler.jsonc with `$schema` for validation.\n\n### Binding Not Available\n- Check binding exists in config\n- For environments, ensure binding defined for that env\n- Local dev: some bindings need `--remote`\n\n### Deployment Failures\n```bash\nwrangler tail # Check logs\nwrangler deploy --dry-run # Validate\nwrangler whoami # Check account limits\n```\n\n### Local Development Issues\n```bash\nrm -rf .wrangler/state # Clear local state\nwrangler dev --remote # Use remote bindings\nwrangler dev --persist-to ./local-state # Custom persist location\nwrangler dev --inspector-port 9229 # Enable debugging\n```\n\n### Testing Issues\n```bash\n# If tests hang, ensure dispose() is called\nworker.dispose() // Always cleanup\n\n# If bindings don't work in tests\nconst worker = await startWorker({ \n config: \"wrangler.jsonc\",\n remote: \"minimal\" // Use remote bindings\n});\n```\n\n## Resources\n\n- Docs: https://developers.cloudflare.com/workers/wrangler/\n- Config: https://developers.cloudflare.com/workers/wrangler/configuration/\n- Commands: https://developers.cloudflare.com/workers/wrangler/commands/\n- Examples: https://github.com/cloudflare/workers-sdk/tree/main/templates\n- Discord: https://discord.gg/cloudflaredev\n\n## See Also\n\n- [README.md](./README.md) - Commands\n- [configuration.md](./configuration.md) - Config\n- [api.md](./api.md) - Programmatic API\n- [patterns.md](./patterns.md) - Workflows\n" }, { "path": "skills/.curated/cloudflare-deploy/references/wrangler/patterns.md", "content": "# Wrangler Development Patterns\n\nCommon workflows and best practices.\n\n## New Worker Project\n\n```bash\nwrangler init my-worker && cd my-worker\nwrangler dev # Develop locally\nwrangler deploy # Deploy\n```\n\n## Local Development\n\n```bash\nwrangler dev # Local mode (fast, simulated)\nwrangler dev --remote # Remote mode (production-accurate)\nwrangler dev --env staging --port 8787\nwrangler dev --inspector-port 9229 # Enable debugging\n```\n\nDebug: chrome://inspect → Configure → localhost:9229\n\n## Secrets\n\n```bash\n# Production\necho \"secret-value\" | wrangler secret put SECRET_KEY\n\n# Local: use .dev.vars (gitignored)\n# SECRET_KEY=local-dev-key\n```\n\n## Adding KV\n\n```bash\nwrangler kv namespace create MY_KV\nwrangler kv namespace create MY_KV --preview\n# Add to wrangler.jsonc: { \"binding\": \"MY_KV\", \"id\": \"abc123\" }\nwrangler deploy\n```\n\n## Adding D1\n\n```bash\nwrangler d1 create my-db\nwrangler d1 migrations create my-db \"initial_schema\"\n# Edit migration file in migrations/, then:\nwrangler d1 migrations apply my-db --local\nwrangler deploy\nwrangler d1 migrations apply my-db --remote\n\n# Time Travel (restore to point in time)\nwrangler d1 time-travel restore my-db --timestamp 2025-01-01T12:00:00Z\n```\n\n## Multi-Environment\n\n```bash\nwrangler deploy --env staging\nwrangler deploy --env production\n```\n\n```jsonc\n{ \"env\": { \"staging\": { \"vars\": { \"ENV\": \"staging\" } } } }\n```\n\n## Testing\n\n### Integration Tests with Node.js Test Runner\n\n```typescript\nimport { startWorker } from \"wrangler\";\nimport { describe, it, before, after } from \"node:test\";\nimport assert from \"node:assert\";\n\ndescribe(\"API\", () => {\n let worker;\n \n before(async () => {\n worker = await startWorker({ \n config: \"wrangler.jsonc\",\n remote: \"minimal\" // Fast tests with real bindings\n });\n });\n \n after(async () => await worker.dispose());\n \n it(\"creates user\", async () => {\n const response = await worker.fetch(\"http://example.com/api/users\", {\n method: \"POST\",\n body: JSON.stringify({ name: \"Alice\" })\n });\n assert.strictEqual(response.status, 201);\n });\n});\n```\n\n### Testing with Vitest\n\nInstall: `npm install -D vitest @cloudflare/vitest-pool-workers`\n\n**vitest.config.ts:**\n```typescript\nimport { defineWorkersConfig } from \"@cloudflare/vitest-pool-workers/config\";\nexport default defineWorkersConfig({\n test: { poolOptions: { workers: { wrangler: { configPath: \"./wrangler.jsonc\" } } } }\n});\n```\n\n**tests/api.test.ts:**\n```typescript\nimport { env, SELF } from \"cloudflare:test\";\nimport { describe, it, expect } from \"vitest\";\n\nit(\"fetches users\", async () => {\n const response = await SELF.fetch(\"https://example.com/api/users\");\n expect(response.status).toBe(200);\n});\n\nit(\"uses bindings\", async () => {\n await env.MY_KV.put(\"key\", \"value\");\n expect(await env.MY_KV.get(\"key\")).toBe(\"value\");\n});\n```\n\n### Multi-Worker Development (Service Bindings)\n\n```typescript\nconst authWorker = await startWorker({ config: \"./auth/wrangler.jsonc\" });\nconst apiWorker = await startWorker({\n config: \"./api/wrangler.jsonc\",\n bindings: { AUTH: authWorker } // Service binding\n});\n\n// Test API calling AUTH\nconst response = await apiWorker.fetch(\"http://example.com/api/protected\");\nawait authWorker.dispose();\nawait apiWorker.dispose();\n```\n\n### Mock External APIs\n\n```typescript\nconst worker = await startWorker({ \n config: \"wrangler.jsonc\",\n outboundService: (req) => {\n const url = new URL(req.url);\n if (url.hostname === \"api.external.com\") {\n return new Response(JSON.stringify({ mocked: true }), {\n headers: { \"content-type\": \"application/json\" }\n });\n }\n return fetch(req); // Pass through other requests\n }\n});\n\n// Test Worker that calls external API\nconst response = await worker.fetch(\"http://example.com/proxy\");\n// Worker internally fetches api.external.com - gets mocked response\n```\n\n## Monitoring & Versions\n\n```bash\nwrangler tail # Real-time logs\nwrangler tail --status error # Filter errors\nwrangler versions list\nwrangler rollback [id]\n```\n\n## TypeScript\n\n```bash\nwrangler types # Generate types from config\n```\n\n```typescript\nexport default {\n async fetch(request: Request, env: Env): Promise {\n return Response.json({ value: await env.MY_KV.get(\"key\") });\n }\n} satisfies ExportedHandler;\n```\n\n## Workers Assets\n\n```jsonc\n{ \"assets\": { \"directory\": \"./dist\", \"binding\": \"ASSETS\" } }\n```\n\n```typescript\nexport default {\n async fetch(request, env) {\n // API routes first\n if (new URL(request.url).pathname.startsWith(\"/api/\")) {\n return Response.json({ data: \"from API\" });\n }\n return env.ASSETS.fetch(request); // Static assets\n }\n}\n```\n\n## See Also\n\n- [README.md](./README.md) - Commands\n- [configuration.md](./configuration.md) - Config\n- [api.md](./api.md) - Programmatic API\n- [gotchas.md](./gotchas.md) - Issues\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/IMPLEMENTATION_SUMMARY.md", "content": "# Zaraz Reference Implementation Summary\n\n## Files Created\n\n| File | Lines | Purpose |\n|------|-------|---------|\n| README.md | 111 | Navigation, decision tree, quick start |\n| api.md | 287 | Web API reference, Zaraz Context |\n| configuration.md | 307 | Dashboard setup, triggers, tools, consent |\n| patterns.md | 430 | SPA, e-commerce, Worker integration |\n| gotchas.md | 317 | Troubleshooting, limits, tool-specific issues |\n| **Total** | **1,452** | **vs 366 original** |\n\n## Key Improvements Applied\n\n### Structure\n- ✅ Created 5-file progressive disclosure system\n- ✅ Added navigation table in README\n- ✅ Added decision tree for routing\n- ✅ Added \"Reading Order by Task\" guide\n- ✅ Cross-referenced files throughout\n\n### New Content Added\n- ✅ Zaraz Context (system/client properties)\n- ✅ History Change trigger for SPA tracking\n- ✅ Context Enrichers pattern\n- ✅ Worker Variables pattern\n- ✅ Consent management deep dive\n- ✅ Tool-specific quirks (GA4, Facebook, Google Ads)\n- ✅ GTM migration guide\n- ✅ Comprehensive troubleshooting\n- ✅ \"When NOT to use Zaraz\" section\n- ✅ TypeScript type definitions\n\n### Preserved Content\n- ✅ All original API methods\n- ✅ E-commerce tracking examples\n- ✅ Consent management\n- ✅ Workers integration (expanded)\n- ✅ Common patterns (expanded)\n- ✅ Debugging tools\n- ✅ Reference links\n\n## Progressive Disclosure Impact\n\n### Before (Monolithic)\nAll tasks loaded 366 lines regardless of need.\n\n### After (Progressive)\n- **Track event task**: README (111) + api.md (287) = 398 lines\n- **Debug issue**: gotchas.md (317) = 317 lines (13% reduction)\n- **Configure tool**: configuration.md (307) = 307 lines (16% reduction)\n- **SPA tracking**: README + patterns.md (SPA section) ~180 lines (51% reduction)\n\n**Net effect:** Task-specific loading reduces unnecessary content by 13-51% depending on use case.\n\n## File Summary\n\n### README.md (111 lines)\n- Overview and core concepts\n- Quick start guide\n- When to use Zaraz vs Workers\n- Navigation table\n- Reading order by task\n- Decision tree\n\n### api.md (287 lines)\n- zaraz.track()\n- zaraz.set()\n- zaraz.ecommerce()\n- Zaraz Context (system/client properties)\n- zaraz.consent API\n- zaraz.debug\n- Cookie methods\n- TypeScript definitions\n\n### configuration.md (307 lines)\n- Dashboard setup flow\n- Trigger types (including History Change)\n- Tool configuration (GA4, Facebook, Google Ads)\n- Actions and action rules\n- Selective loading\n- Consent management setup\n- Privacy features\n- Testing workflow\n\n### patterns.md (430 lines)\n- SPA tracking (React, Vue, Next.js)\n- User identification flows\n- Complete e-commerce funnel\n- A/B testing\n- Worker integration (Context Enrichers, Worker Variables, HTML injection)\n- Multi-tool coordination\n- GTM migration\n- Best practices\n\n### gotchas.md (317 lines)\n- Events not firing (5-step debug process)\n- Consent issues\n- SPA tracking pitfalls\n- Performance issues\n- Tool-specific quirks\n- Data layer issues\n- Limits table\n- When NOT to use Zaraz\n- Debug checklist\n\n## Quality Metrics\n\n- ✅ All files use consistent markdown formatting\n- ✅ Code examples include language tags\n- ✅ Tables for structured data (limits, parameters, comparisons)\n- ✅ Problem → Cause → Solution format in gotchas\n- ✅ Cross-references between files\n- ✅ No \"see documentation\" placeholders\n- ✅ Real, actionable examples throughout\n- ✅ Verified API syntax for Workers\n\n## Original Backup\n\nOriginal SKILL.md preserved as `_SKILL_old.md` for reference.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/README.md", "content": "# Cloudflare Zaraz\n\nExpert guidance for Cloudflare Zaraz - server-side tag manager for loading third-party tools at the edge.\n\n## What is Zaraz?\n\nZaraz offloads third-party scripts (analytics, ads, chat, marketing) to Cloudflare's edge, improving site speed, privacy, and security. Zero client-side performance impact.\n\n**Core Concepts:**\n- **Server-side execution** - Scripts run on Cloudflare, not user's browser\n- **Single HTTP request** - All tools loaded via one endpoint\n- **Privacy-first** - Control data sent to third parties\n- **No client-side JS overhead** - Minimal browser impact\n\n## Quick Start\n\n1. Navigate to domain > Zaraz in Cloudflare dashboard\n2. Click \"Start setup\"\n3. Add tools (Google Analytics, Facebook Pixel, etc.)\n4. Configure triggers (when tools fire)\n5. Add tracking code to your site:\n\n```javascript\n// Track page view\nzaraz.track('page_view');\n\n// Track custom event\nzaraz.track('button_click', { button_id: 'cta' });\n\n// Set user properties\nzaraz.set('userId', 'user_123');\n```\n\n## When to Use Zaraz\n\n**Use Zaraz when:**\n- Adding multiple third-party tools (analytics, ads, marketing)\n- Site performance is critical (no client-side JS overhead)\n- Privacy compliance required (GDPR, CCPA)\n- Non-technical teams need to manage tools\n\n**Use Workers directly when:**\n- Building custom server-side tracking logic\n- Need full control over data processing\n- Integrating with complex backend systems\n- Zaraz's tool library doesn't meet needs\n\n## In This Reference\n\n| File | Purpose | When to Read |\n|------|---------|--------------|\n| [api.md](./api.md) | Web API, zaraz object, consent methods | Implementing tracking calls |\n| [configuration.md](./configuration.md) | Dashboard setup, triggers, tools | Initial setup, adding tools |\n| [patterns.md](./patterns.md) | SPA, e-commerce, Worker integration | Best practices, common scenarios |\n| [gotchas.md](./gotchas.md) | Troubleshooting, limits, pitfalls | Debugging issues |\n\n## Reading Order by Task\n\n| Task | Files to Read |\n|------|---------------|\n| Add analytics to site | README → configuration.md |\n| Track custom events | README → api.md |\n| Debug tracking issues | gotchas.md |\n| SPA tracking | api.md → patterns.md (SPA section) |\n| E-commerce tracking | api.md#ecommerce → patterns.md#ecommerce |\n| Worker integration | patterns.md#worker-integration |\n| GDPR compliance | api.md#consent → configuration.md#consent |\n\n## Decision Tree\n\n```\nWhat do you need?\n\n├─ Track events in browser → api.md\n│ ├─ Page views, clicks → zaraz.track()\n│ ├─ User properties → zaraz.set()\n│ └─ E-commerce → zaraz.ecommerce()\n│\n├─ Configure Zaraz → configuration.md\n│ ├─ Add GA4/Facebook → tools setup\n│ ├─ When tools fire → triggers\n│ └─ GDPR consent → consent purposes\n│\n├─ Integrate with Workers → patterns.md#worker-integration\n│ ├─ Enrich context → Context Enrichers\n│ └─ Inject tracking → HTML rewriting\n│\n└─ Debug issues → gotchas.md\n ├─ Events not firing → troubleshooting\n ├─ Consent issues → consent debugging\n └─ Performance → debugging tools\n```\n\n## Key Features\n\n- **100+ Pre-built Tools** - GA4, Facebook, Google Ads, TikTok, etc.\n- **Zero Client Impact** - Runs at Cloudflare's edge, not browser\n- **Privacy Controls** - Consent management, data filtering\n- **Custom Tools** - Build Managed Components for proprietary systems\n- **Worker Integration** - Enrich context, compute dynamic values\n- **Debug Mode** - Real-time event inspection\n\n## Reference\n\n- [Zaraz Docs](https://developers.cloudflare.com/zaraz/)\n- [Web API](https://developers.cloudflare.com/zaraz/web-api/)\n- [Managed Components](https://developers.cloudflare.com/zaraz/advanced/load-custom-managed-component/)\n\n---\n\nThis skill focuses exclusively on Zaraz. For Workers development, see `cloudflare-workers` skill.\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/api.md", "content": "# Zaraz Web API\n\nClient-side JavaScript API for tracking events, setting properties, and managing consent.\n\n## zaraz.track()\n\n```javascript\nzaraz.track('button_click');\nzaraz.track('purchase', { value: 99.99, currency: 'USD', item_id: '12345' });\nzaraz.track('pageview', { page_path: '/products', page_title: 'Products' }); // SPA\n```\n\n**Params:** `eventName` (string), `properties` (object, optional). Fire-and-forget.\n\n## zaraz.set()\n\n```javascript\nzaraz.set('userId', 'user_12345');\nzaraz.set({ email: '[email protected]', plan: 'premium', country: 'US' });\n```\n\nProperties persist for page session. Use for user identification and segmentation.\n\n## zaraz.ecommerce()\n\n```javascript\nzaraz.ecommerce('Product Viewed', { product_id: 'SKU123', name: 'Widget', price: 49.99 });\nzaraz.ecommerce('Product Added', { product_id: 'SKU123', quantity: 2, price: 49.99 });\nzaraz.ecommerce('Order Completed', {\n order_id: 'ORD-789', total: 149.98, currency: 'USD',\n products: [{ product_id: 'SKU123', quantity: 2, price: 49.99 }]\n});\n```\n\n**Events:** `Product Viewed`, `Product Added`, `Product Removed`, `Cart Viewed`, `Checkout Started`, `Order Completed`\n\nTools auto-map to GA4, Facebook CAPI, etc.\n\n## System Properties (Triggers)\n\n```\n{{system.page.url}} {{system.page.title}} {{system.page.referrer}}\n{{system.device.ip}} {{system.device.userAgent}} {{system.device.language}}\n{{system.cookies.name}} {{client.__zarazTrack.userId}}\n```\n\n## zaraz.consent\n\n```javascript\n// Check\nconst purposes = zaraz.consent.getAll(); // { analytics: true, marketing: false }\n\n// Set\nzaraz.consent.modal = true; // Show modal\nzaraz.consent.setAll({ analytics: true, marketing: false });\nzaraz.consent.set('marketing', true);\n\n// Listen\nzaraz.consent.addEventListener('consentChanged', () => {\n if (zaraz.consent.getAll().marketing) zaraz.track('marketing_consent_granted');\n});\n```\n\n**Flow:** Configure purposes in dashboard → Map tools to purposes → Show modal/set programmatically → Tools fire when allowed\n\n## zaraz.debug\n\n```javascript\nzaraz.debug = true;\nzaraz.track('test_event');\nconsole.log(zaraz.tools); // View loaded tools\n```\n\n## Cookie Methods\n\n```javascript\nzaraz.getCookie('session_id'); // Zaraz namespace\nzaraz.readCookie('_ga'); // Any cookie\n```\n\n## Async Behavior\n\nAll methods fire-and-forget. Events batched and sent asynchronously:\n\n```javascript\nzaraz.track('event1');\nzaraz.set('prop', 'value');\nzaraz.track('event2'); // All batched\n```\n\n## TypeScript Types\n\n```typescript\ninterface Zaraz {\n track(event: string, properties?: Record): void;\n set(key: string, value: unknown): void;\n set(properties: Record): void;\n ecommerce(event: string, properties: Record): void;\n consent: {\n getAll(): Record;\n setAll(purposes: Record): void;\n set(purpose: string, value: boolean): void;\n addEventListener(event: 'consentChanged', callback: () => void): void;\n modal: boolean;\n };\n debug: boolean;\n tools?: string[];\n getCookie(name: string): string | undefined;\n readCookie(name: string): string | undefined;\n}\ndeclare global { interface Window { zaraz: Zaraz; } }\n```\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/configuration.md", "content": "# Zaraz Configuration\n\n## Dashboard Setup\n\n1. Domain → Zaraz → Start setup\n2. Add tool (e.g., Google Analytics 4)\n3. Enter credentials (GA4: `G-XXXXXXXXXX`)\n4. Configure triggers\n5. Save and Publish\n\n## Triggers\n\n| Type | When | Use Case |\n|------|------|----------|\n| Pageview | Page load | Track page views |\n| Click | Element clicked | Button tracking |\n| Form Submission | Form submitted | Lead capture |\n| History Change | URL changes (SPA) | React/Vue routing |\n| Variable Match | Custom condition | Conditional firing |\n\n### History Change (SPA)\n\n```\nType: History Change\nEvent: pageview\n```\n\nFires on `pushState`, `replaceState`, hash changes. **No manual tracking needed.**\n\n### Click Trigger\n\n```\nType: Click\nCSS Selector: .buy-button\nEvent: purchase_intent\nProperties:\n button_text: {{system.clickElement.text}}\n```\n\n## Tool Configuration\n\n**GA4:**\n```\nMeasurement ID: G-XXXXXXXXXX\nEvents: page_view, purchase, user_engagement\n```\n\n**Facebook Pixel:**\n```\nPixel ID: 1234567890123456\nEvents: PageView, Purchase, AddToCart\n```\n\n**Google Ads:**\n```\nConversion ID: AW-XXXXXXXXX\nConversion Label: YYYYYYYYYY\n```\n\n## Consent Management\n\n1. Settings → Consent → Create purposes (analytics, marketing)\n2. Map tools to purposes\n3. Set behavior: \"Do not load until consent granted\"\n\n**Programmatic consent:**\n```javascript\nzaraz.consent.setAll({ analytics: true, marketing: true });\n```\n\n## Privacy Features\n\n| Feature | Default |\n|---------|---------|\n| IP Anonymization | Enabled |\n| Cookie Control | Via consent purposes |\n| GDPR/CCPA | Consent modal |\n\n## Testing\n\n1. **Preview Mode** - test without publishing\n2. **Debug Mode** - `zaraz.debug = true`\n3. **Network tab** - filter \"zaraz\"\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Event properties | 100KB |\n| Consent purposes | 20 |\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/gotchas.md", "content": "# Zaraz Gotchas\n\n## Events Not Firing\n\n**Check:**\n1. Tool enabled in dashboard (green dot)\n2. Trigger conditions met\n3. Consent granted for tool's purpose\n4. Tool credentials correct (GA4: `G-XXXXXXXXXX`, FB: numeric only)\n\n**Debug:**\n```javascript\nzaraz.debug = true;\nconsole.log('Tools:', zaraz.tools);\nconsole.log('Consent:', zaraz.consent.getAll());\n```\n\n## Consent Issues\n\n**Modal not showing:**\n```javascript\n// Clear consent cookie\ndocument.cookie = 'zaraz-consent=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;';\nlocation.reload();\n```\n\n**Tools firing before consent:** Map tool to consent purpose with \"Do not load until consent granted\".\n\n## SPA Tracking\n\n**Route changes not tracked:**\n1. Configure History Change trigger in dashboard\n2. Hash routing (`#/path`) requires manual tracking:\n```javascript\nwindow.addEventListener('hashchange', () => {\n zaraz.track('pageview', { page_path: location.pathname + location.hash });\n});\n```\n\n**React fix:**\n```javascript\nconst location = useLocation();\nuseEffect(() => {\n zaraz.track('pageview', { page_path: location.pathname });\n}, [location]); // Include dependency\n```\n\n## Performance\n\n**Slow page load:**\n- Audit tool count (50+ degrades performance)\n- Disable blocking triggers unless required\n- Reduce event payload size (<100KB)\n\n## Tool-Specific Issues\n\n| Tool | Issue | Fix |\n|------|-------|-----|\n| GA4 | Events not in real-time | Wait 5-10 min, use DebugView |\n| Facebook | Invalid Pixel ID | Use numeric only (no `fbpx_` prefix) |\n| Google Ads | Conversions not attributed | Include `send_to: 'AW-XXX/LABEL'` |\n\n## Data Layer\n\n- Properties persist per page only - set on each page load\n- Nested access: `{{client.__zarazTrack.user.plan}}`\n\n## Limits\n\n| Resource | Limit |\n|----------|-------|\n| Request size | 100KB |\n| Consent purposes | 20 |\n| API rate | 1000 req/sec |\n\n## When NOT to Use Zaraz\n\n- Server-to-server tracking (use Workers)\n- Real-time bidirectional communication\n- Binary data transmission\n- Authentication flows\n" }, { "path": "skills/.curated/cloudflare-deploy/references/zaraz/patterns.md", "content": "# Zaraz Patterns\n\n## SPA Tracking\n\n**History Change Trigger (Recommended):** Configure in dashboard - no code needed, Zaraz auto-detects route changes.\n\n**Manual tracking (React/Vue/Next.js):**\n```javascript\n// On route change\nzaraz.track('pageview', { page_path: pathname, page_title: document.title });\n```\n\n## User Identification\n\n```javascript\n// Login\nzaraz.set({ userId: user.id, email: user.email, plan: user.plan });\nzaraz.track('login', { method: 'oauth' });\n\n// Logout - set to null (cannot clear)\nzaraz.set('userId', null);\n```\n\n## E-commerce Funnel\n\n| Event | Method |\n|-------|--------|\n| View | `zaraz.ecommerce('Product Viewed', { product_id, name, price })` |\n| Add to cart | `zaraz.ecommerce('Product Added', { product_id, quantity })` |\n| Checkout | `zaraz.ecommerce('Checkout Started', { cart_id, products: [...] })` |\n| Purchase | `zaraz.ecommerce('Order Completed', { order_id, total, products })` |\n\n## A/B Testing\n\n```javascript\nzaraz.set('experiment_checkout', variant);\nzaraz.track('experiment_viewed', { experiment_id: 'checkout', variant });\n// On conversion\nzaraz.track('experiment_conversion', { experiment_id, variant, value });\n```\n\n## Worker Integration\n\n**Context Enricher** - Modify context before tools execute:\n```typescript\nexport default {\n async fetch(request, env) {\n const body = await request.json();\n body.system.userRegion = request.cf?.region;\n return Response.json(body);\n }\n};\n```\nConfigure: Zaraz > Settings > Context Enrichers\n\n**Worker Variables** - Compute dynamic values server-side, use as `{{worker.variable_name}}`.\n\n## GTM Migration\n\n| GTM | Zaraz |\n|-----|-------|\n| `dataLayer.push({event: 'purchase'})` | `zaraz.ecommerce('Order Completed', {...})` |\n| `{{Page URL}}` | `{{system.page.url}}` |\n| `{{Page Title}}` | `{{system.page.title}}` |\n| Page View trigger | Pageview trigger |\n| Click trigger | Click (selector: `*`) |\n\n## Best Practices\n\n1. Use dashboard triggers over inline code\n2. Enable History Change for SPAs (no manual code)\n3. Debug with `zaraz.debug = true`\n4. Implement consent early (GDPR/CCPA)\n5. Use Context Enrichers for sensitive/server data\n" }, { "path": "skills/.curated/develop-web-game/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don\\'t include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/develop-web-game/SKILL.md", "content": "---\nname: \"develop-web-game\"\ndescription: \"Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with render_game_to_text.\"\n---\n\n\n# Develop Web Game\n\nBuild games in small steps and validate every change. Treat each iteration as: implement → act → pause → observe → adjust.\n\n## Skill paths (set once)\n\n```bash\nexport CODEX_HOME=\"${CODEX_HOME:-$HOME/.codex}\"\nexport WEB_GAME_CLIENT=\"$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js\"\nexport WEB_GAME_ACTIONS=\"$CODEX_HOME/skills/develop-web-game/references/action_payloads.json\"\n```\n\nUser-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).\n\n## Workflow\n\n1. **Pick a goal.** Define a single feature or behavior to implement.\n2. **Implement small.** Make the smallest change that moves the game forward.\n3. **Ensure integration points.** Provide a single canvas and `window.render_game_to_text` so the test loop can read state.\n4. **Add `window.advanceTime(ms)`.** Strongly prefer a deterministic step hook so the Playwright script can advance frames reliably; without it, automated tests can be flaky.\n5. **Initialize progress.md.** If `progress.md` exists, read it first and confirm the original user prompt is recorded at the top (prefix with `Original prompt:`). Also note any TODOs and suggestions left by the previous agent. If missing, create it and write `Original prompt: ` at the top before appending updates.\n6. **Verify Playwright availability.** Ensure `playwright` is available (local dependency or global install). If unsure, check `npx` first.\n7. **Run the Playwright test script.** You must run `$WEB_GAME_CLIENT` after each meaningful change; do not invent a new client unless required.\n8. **Use the payload reference.** Base actions on `$WEB_GAME_ACTIONS` to avoid guessing keys.\n9. **Inspect state.** Capture screenshots and text state after each burst.\n10. **Inspect screenshots.** Open the latest screenshot, verify expected visuals, fix any issues, and rerun the script. Repeat until correct.\n11. **Verify controls and state (multi-step focus).** Exhaustively exercise all important interactions. For each, think through the full multi-step sequence it implies (cause → intermediate states → outcome) and verify the entire chain works end-to-end. Confirm `render_game_to_text` reflects the same state shown on screen. If anything is off, fix and rerun.\n Examples of important interactions: move, jump, shoot/attack, interact/use, select/confirm/cancel in menus, pause/resume, restart, and any special abilities or puzzle actions defined by the request. Multi-step examples: shooting an enemy should reduce its health; when health reaches 0 it should disappear and update the score; collecting a key should unlock a door and allow level progression.\n12. **Check errors.** Review console errors and fix the first new issue before continuing.\n13. **Reset between scenarios.** Avoid cross-test state when validating distinct features.\n14. **Iterate with small deltas.** Change one variable at a time (frames, inputs, timing, positions), then repeat steps 7–13 until stable.\n\nExample command (actions required):\n```\nnode \"$WEB_GAME_CLIENT\" --url http://localhost:5173 --actions-file \"$WEB_GAME_ACTIONS\" --click-selector \"#start-btn\" --iterations 3 --pause-ms 250\n```\n\nExample actions (inline JSON):\n```json\n{\n \"steps\": [\n { \"buttons\": [\"left_mouse_button\"], \"frames\": 2, \"mouse_x\": 120, \"mouse_y\": 80 },\n { \"buttons\": [], \"frames\": 6 },\n { \"buttons\": [\"right\"], \"frames\": 8 },\n { \"buttons\": [\"space\"], \"frames\": 4 }\n ]\n}\n```\n\n## Test Checklist\n\nTest any new features added for the request and any areas your logic changes could affect. Identify issues, fix them, and re-run the tests to confirm they’re resolved.\n\nExamples of things to test:\n- Primary movement/interaction inputs (e.g., move, jump, shoot, confirm/select).\n- Win/lose or success/fail transitions.\n- Score/health/resource changes.\n- Boundary conditions (collisions, walls, screen edges).\n- Menu/pause/start flow if present.\n- Any special actions tied to the request (powerups, combos, abilities, puzzles, timers).\n\n## Test Artifacts to Review\n\n- Latest screenshots from the Playwright run.\n- Latest `render_game_to_text` JSON output.\n- Console error logs (fix the first new error before continuing).\nYou must actually open and visually inspect the latest screenshots after running the Playwright script, not just generate them. Ensure everything that should be visible on screen is actually visible. Go beyond the start screen and capture gameplay screenshots that cover all newly added features. Treat the screenshots as the source of truth; if something is missing, it is missing in the build. If you suspect a headless/WebGL capture issue, rerun the Playwright script in headed mode and re-check. Fix and rerun in a tight loop until the screenshots and text state look correct. Once fixes are verified, re-test all important interactions and controls, confirm they work, and ensure your changes did not introduce regressions. If they did, fix them and rerun everything in a loop until interactions, text state, and controls all work as expected. Be exhaustive in testing controls; broken games are not acceptable.\n\n## Core Game Guidelines\n\n### Canvas + Layout\n- Prefer a single canvas centered in the window.\n\n### Visuals\n- Keep on-screen text minimal; show controls on a start/menu screen rather than overlaying them during play.\n- Avoid overly dark scenes unless the design calls for it. Make key elements easy to see.\n- Draw the background on the canvas itself instead of relying on CSS backgrounds.\n\n### Text State Output (render_game_to_text)\nExpose a `window.render_game_to_text` function that returns a concise JSON string representing the current game state. The text should include enough information to play the game without visuals.\n\nMinimal pattern:\n```js\nfunction renderGameToText() {\n const payload = {\n mode: state.mode,\n player: { x: state.player.x, y: state.player.y, r: state.player.r },\n entities: state.entities.map((e) => ({ x: e.x, y: e.y, r: e.r })),\n score: state.score,\n };\n return JSON.stringify(payload);\n}\nwindow.render_game_to_text = renderGameToText;\n```\n\nKeep the payload succinct and biased toward on-screen/interactive elements. Prefer current, visible entities over full history.\nInclude a clear coordinate system note (origin and axis directions), and encode all player-relevant state: player position/velocity, active obstacles/enemies, collectibles, timers/cooldowns, score, and any mode/state flags needed to make correct decisions. Avoid large histories; only include what's currently relevant and visible.\n\n### Time Stepping Hook\nProvide a deterministic time-stepping hook so the Playwright client can advance the game in controlled increments. Expose `window.advanceTime(ms)` (or a thin wrapper that forwards to your game update loop) and have the game loop use it when present.\nThe Playwright test script uses this hook to step frames deterministically during automated testing.\n\nMinimal pattern:\n```js\nwindow.advanceTime = (ms) => {\n const steps = Math.max(1, Math.round(ms / (1000 / 60)));\n for (let i = 0; i < steps; i++) update(1 / 60);\n render();\n};\n```\n\n### Fullscreen Toggle\n- Use a single key (prefer `f`) to toggle fullscreen on/off.\n- Allow `Esc` to exit fullscreen.\n- When fullscreen toggles, resize the canvas/rendering so visuals and input mapping stay correct.\n\n## Progress Tracking\n\nCreate a `progress.md` file if it doesn't exist, and append TODOs, notes, gotchas, and loose ends as you go so another agent can pick up seamlessly.\nIf a `progress.md` file already exists, read it first, including the original user prompt at the top (you may be continuing another agent's work). Do not overwrite the original prompt; preserve it.\nUpdate `progress.md` after each meaningful chunk of work (feature added, bug found, test run, or decision made).\nAt the end of your work, leave TODOs and suggestions for the next agent in `progress.md`.\n\n## Playwright Prerequisites\n\n- Prefer a local `playwright` dependency if the project already has it.\n- If unsure whether Playwright is available, check for `npx`:\n ```\n command -v npx >/dev/null 2>&1\n ```\n- If `npx` is missing, install Node/npm and then install Playwright globally:\n ```\n npm install -g @playwright/mcp@latest\n ```\n- Do not switch to `@playwright/test` unless explicitly asked; stick to the client script.\n\n## Scripts\n\n- `$WEB_GAME_CLIENT` (installed default: `$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js`) — Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. You must pass an action burst via `--actions-file`, `--actions-json`, or `--click`.\n\n## References\n\n- `$WEB_GAME_ACTIONS` (installed default: `$CODEX_HOME/skills/develop-web-game/references/action_payloads.json`) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.\n" }, { "path": "skills/.curated/develop-web-game/agents/openai.yaml", "content": "interface:\n display_name: \"Develop Web Game\"\n short_description: \"Web game dev + Playwright test loop\"\n icon_small: \"./assets/game-small.svg\"\n icon_large: \"./assets/game.png\"\n default_prompt: \"Build and iterate a playable web game in this workspace, validating changes with a Playwright loop.\"\n" }, { "path": "skills/.curated/develop-web-game/references/action_payloads.json", "content": "{\n \"steps\": [\n { \"buttons\": [\"left\"], \"frames\": 6 },\n { \"buttons\": [], \"frames\": 4 },\n { \"buttons\": [\"space\"], \"frames\": 3 }\n ]\n}\n" }, { "path": "skills/.curated/develop-web-game/scripts/web_game_playwright_client.js", "content": "import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { chromium } from \"playwright\";\n\nfunction parseArgs(argv) {\n const args = {\n url: null,\n iterations: 3,\n pauseMs: 250,\n headless: true,\n screenshotDir: \"output/web-game\",\n actionsFile: null,\n actionsJson: null,\n click: null,\n clickSelector: null,\n };\n for (let i = 2; i < argv.length; i++) {\n const arg = argv[i];\n const next = argv[i + 1];\n if (arg === \"--url\" && next) {\n args.url = next;\n i++;\n } else if (arg === \"--iterations\" && next) {\n args.iterations = parseInt(next, 10);\n i++;\n } else if (arg === \"--pause-ms\" && next) {\n args.pauseMs = parseInt(next, 10);\n i++;\n } else if (arg === \"--headless\" && next) {\n args.headless = next !== \"0\" && next !== \"false\";\n i++;\n } else if (arg === \"--screenshot-dir\" && next) {\n args.screenshotDir = next;\n i++;\n } else if (arg === \"--actions-file\" && next) {\n args.actionsFile = next;\n i++;\n } else if (arg === \"--actions-json\" && next) {\n args.actionsJson = next;\n i++;\n } else if (arg === \"--click\" && next) {\n const parts = next.split(\",\").map((v) => parseFloat(v.trim()));\n if (parts.length === 2 && parts.every((v) => Number.isFinite(v))) {\n args.click = { x: parts[0], y: parts[1] };\n }\n i++;\n } else if (arg === \"--click-selector\" && next) {\n args.clickSelector = next;\n i++;\n }\n }\n if (!args.url) {\n throw new Error(\"--url is required\");\n }\n return args;\n}\n\nconst buttonNameToKey = {\n up: \"ArrowUp\",\n down: \"ArrowDown\",\n left: \"ArrowLeft\",\n right: \"ArrowRight\",\n enter: \"Enter\",\n space: \"Space\",\n a: \"KeyA\",\n b: \"KeyB\",\n};\n\nasync function sleep(ms) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction ensureDir(p) {\n fs.mkdirSync(p, { recursive: true });\n}\n\nfunction makeVirtualTimeShim() {\n return `(() => {\n const pending = new Set();\n const origSetTimeout = window.setTimeout.bind(window);\n const origSetInterval = window.setInterval.bind(window);\n const origRequestAnimationFrame = window.requestAnimationFrame.bind(window);\n\n window.__vt_pending = pending;\n\n window.setTimeout = (fn, t, ...rest) => {\n const task = {};\n pending.add(task);\n return origSetTimeout(() => {\n pending.delete(task);\n fn(...rest);\n }, t);\n };\n\n window.setInterval = (fn, t, ...rest) => {\n const task = {};\n pending.add(task);\n return origSetInterval(() => {\n fn(...rest);\n }, t);\n };\n\n window.requestAnimationFrame = (fn) => {\n const task = {};\n pending.add(task);\n return origRequestAnimationFrame((ts) => {\n pending.delete(task);\n fn(ts);\n });\n };\n\n window.advanceTime = (ms) => {\n return new Promise((resolve) => {\n const start = performance.now();\n function step(now) {\n if (now - start >= ms) return resolve();\n origRequestAnimationFrame(step);\n }\n origRequestAnimationFrame(step);\n });\n };\n\n window.__drainVirtualTimePending = () => pending.size;\n })();`;\n}\n\nasync function getCanvasHandle(page) {\n const handle = await page.evaluateHandle(() => {\n let best = null;\n let bestArea = 0;\n for (const canvas of document.querySelectorAll(\"canvas\")) {\n const area = (canvas.width || canvas.clientWidth || 0) * (canvas.height || canvas.clientHeight || 0);\n if (area > bestArea) {\n bestArea = area;\n best = canvas;\n }\n }\n return best;\n });\n return handle.asElement();\n}\n\nasync function captureCanvasPngBase64(canvas) {\n return canvas.evaluate((c) => {\n if (!c || typeof c.toDataURL !== \"function\") return \"\";\n const data = c.toDataURL(\"image/png\");\n const idx = data.indexOf(\",\");\n return idx === -1 ? \"\" : data.slice(idx + 1);\n });\n}\n\nasync function isCanvasTransparent(canvas) {\n if (!canvas) return true;\n return canvas.evaluate((c) => {\n try {\n const w = c.width || c.clientWidth || 0;\n const h = c.height || c.clientHeight || 0;\n if (!w || !h) return true;\n const size = Math.max(1, Math.min(16, w, h));\n const probe = document.createElement(\"canvas\");\n probe.width = size;\n probe.height = size;\n const ctx = probe.getContext(\"2d\");\n if (!ctx) return true;\n ctx.drawImage(c, 0, 0, size, size);\n const data = ctx.getImageData(0, 0, size, size).data;\n for (let i = 3; i < data.length; i += 4) {\n if (data[i] !== 0) return false;\n }\n return true;\n } catch {\n return false;\n }\n });\n}\n\nasync function captureScreenshot(page, canvas, outPath) {\n let buffer = null;\n let base64 = canvas ? await captureCanvasPngBase64(canvas) : \"\";\n if (base64) {\n buffer = Buffer.from(base64, \"base64\");\n const transparent = canvas ? await isCanvasTransparent(canvas) : false;\n if (transparent) buffer = null;\n }\n if (!buffer && canvas) {\n try {\n buffer = await canvas.screenshot({ type: \"png\" });\n } catch {\n buffer = null;\n }\n }\n if (!buffer) {\n const bbox = canvas ? await canvas.boundingBox() : null;\n if (bbox) {\n buffer = await page.screenshot({\n type: \"png\",\n omitBackground: false,\n clip: bbox,\n });\n } else {\n buffer = await page.screenshot({ type: \"png\", omitBackground: false });\n }\n }\n fs.writeFileSync(outPath, buffer);\n}\n\nclass ConsoleErrorTracker {\n constructor() {\n this._seen = new Set();\n this._errors = [];\n }\n\n ingest(err) {\n const key = JSON.stringify(err);\n if (this._seen.has(key)) return;\n this._seen.add(key);\n this._errors.push(err);\n }\n\n drain() {\n const next = [...this._errors];\n this._errors = [];\n return next;\n }\n}\n\nasync function doChoreography(page, canvas, steps) {\n for (const step of steps) {\n const buttons = new Set(step.buttons || []);\n for (const button of buttons) {\n if (button === \"left_mouse_button\" || button === \"right_mouse_button\") {\n const bbox = canvas ? await canvas.boundingBox() : null;\n if (!bbox) continue;\n const x = typeof step.mouse_x === \"number\" ? step.mouse_x : bbox.width / 2;\n const y = typeof step.mouse_y === \"number\" ? step.mouse_y : bbox.height / 2;\n await page.mouse.move(bbox.x + x, bbox.y + y);\n await page.mouse.down({ button: button === \"left_mouse_button\" ? \"left\" : \"right\" });\n } else if (buttonNameToKey[button]) {\n await page.keyboard.down(buttonNameToKey[button]);\n }\n }\n\n const frames = step.frames || 1;\n for (let i = 0; i < frames; i++) {\n await page.evaluate(async () => {\n if (typeof window.advanceTime === \"function\") {\n await window.advanceTime(1000 / 60);\n }\n });\n }\n\n for (const button of buttons) {\n if (button === \"left_mouse_button\" || button === \"right_mouse_button\") {\n await page.mouse.up({ button: button === \"left_mouse_button\" ? \"left\" : \"right\" });\n } else if (buttonNameToKey[button]) {\n await page.keyboard.up(buttonNameToKey[button]);\n }\n }\n }\n}\n\nasync function main() {\n const args = parseArgs(process.argv);\n ensureDir(args.screenshotDir);\n\n const browser = await chromium.launch({\n headless: args.headless,\n args: [\"--use-gl=angle\", \"--use-angle=swiftshader\"],\n });\n const page = await browser.newPage();\n const consoleErrors = new ConsoleErrorTracker();\n\n page.on(\"console\", (msg) => {\n if (msg.type() !== \"error\") return;\n consoleErrors.ingest({ type: \"console.error\", text: msg.text() });\n });\n page.on(\"pageerror\", (err) => {\n consoleErrors.ingest({ type: \"pageerror\", text: String(err) });\n });\n\n await page.addInitScript({ content: makeVirtualTimeShim() });\n await page.goto(args.url, { waitUntil: \"domcontentloaded\" });\n await page.waitForTimeout(500);\n await page.evaluate(() => {\n window.dispatchEvent(new Event(\"resize\"));\n });\n\n let canvas = await getCanvasHandle(page);\n\n if (args.clickSelector) {\n try {\n await page.click(args.clickSelector, { timeout: 5000 });\n await page.waitForTimeout(250);\n } catch (err) {\n console.warn(\"Failed to click selector\", args.clickSelector, err);\n }\n }\n let steps = null;\n if (args.actionsFile) {\n const raw = fs.readFileSync(args.actionsFile, \"utf-8\");\n const parsed = JSON.parse(raw);\n if (Array.isArray(parsed)) steps = parsed;\n if (parsed && Array.isArray(parsed.steps)) steps = parsed.steps;\n } else if (args.actionsJson) {\n const parsed = JSON.parse(args.actionsJson);\n if (Array.isArray(parsed)) steps = parsed;\n if (parsed && Array.isArray(parsed.steps)) steps = parsed.steps;\n } else if (args.click) {\n steps = [\n {\n buttons: [\"left_mouse_button\"],\n frames: 2,\n mouse_x: args.click.x,\n mouse_y: args.click.y,\n },\n ];\n }\n if (!steps) {\n throw new Error(\"Actions are required. Use --actions-file, --actions-json, or --click.\");\n }\n\n for (let i = 0; i < args.iterations; i++) {\n if (!canvas) canvas = await getCanvasHandle(page);\n await doChoreography(page, canvas, steps);\n await sleep(args.pauseMs);\n\n const shotPath = path.join(args.screenshotDir, `shot-${i}.png`);\n await captureScreenshot(page, canvas, shotPath);\n\n const text = await page.evaluate(() => {\n if (typeof window.render_game_to_text === \"function\") {\n return window.render_game_to_text();\n }\n return null;\n });\n if (text) {\n fs.writeFileSync(path.join(args.screenshotDir, `state-${i}.json`), text);\n }\n\n const freshErrors = consoleErrors.drain();\n if (freshErrors.length) {\n fs.writeFileSync(\n path.join(args.screenshotDir, `errors-${i}.json`),\n JSON.stringify(freshErrors, null, 2)\n );\n break;\n }\n }\n\n await browser.close();\n}\n\nmain().catch((err) => {\n console.error(err);\n process.exit(1);\n});\n" }, { "path": "skills/.curated/doc/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don\\'t include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/doc/SKILL.md", "content": "---\nname: \"doc\"\ndescription: \"Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks.\"\n---\n\n\n# DOCX Skill\n\n## When to use\n- Read or review DOCX content where layout matters (tables, diagrams, pagination).\n- Create or edit DOCX files with professional formatting.\n- Validate visual layout before delivery.\n\n## Workflow\n1. Prefer visual review (layout, tables, diagrams).\n - If `soffice` and `pdftoppm` are available, convert DOCX -> PDF -> PNGs.\n - Or use `scripts/render_docx.py` (requires `pdf2image` and Poppler).\n - If these tools are missing, install them or ask the user to review rendered pages locally.\n2. Use `python-docx` for edits and structured creation (headings, styles, tables, lists).\n3. After each meaningful change, re-render and inspect the pages.\n4. If visual review is not possible, extract text with `python-docx` as a fallback and call out layout risk.\n5. Keep intermediate outputs organized and clean up after final approval.\n\n## Temp and output conventions\n- Use `tmp/docs/` for intermediate files; delete when done.\n- Write final artifacts under `output/doc/` when working in this repo.\n- Keep filenames stable and descriptive.\n\n## Dependencies (install if missing)\nPrefer `uv` for dependency management.\n\nPython packages:\n```\nuv pip install python-docx pdf2image\n```\nIf `uv` is unavailable:\n```\npython3 -m pip install python-docx pdf2image\n```\nSystem tools (for rendering):\n```\n# macOS (Homebrew)\nbrew install libreoffice poppler\n\n# Ubuntu/Debian\nsudo apt-get install -y libreoffice poppler-utils\n```\n\nIf installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.\n\n## Environment\nNo required environment variables.\n\n## Rendering commands\nDOCX -> PDF:\n```\nsoffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX\n```\n\nPDF -> PNGs:\n```\npdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME\n```\n\nBundled helper:\n```\npython3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages\n```\n\n## Quality expectations\n- Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.\n- Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.\n- Charts, tables, and visuals must be legible in rendered pages with correct alignment.\n- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.\n- Citations and references must be human-readable; never leave tool tokens or placeholder strings.\n\n## Final checks\n- Re-render and inspect every page at 100% zoom before final delivery.\n- Fix any spacing, alignment, or pagination issues and repeat the render loop.\n- Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.\n" }, { "path": "skills/.curated/doc/agents/openai.yaml", "content": "interface:\n display_name: \"Word Docs\"\n short_description: \"Edit and review docx files\"\n icon_small: \"./assets/doc-small.svg\"\n icon_large: \"./assets/doc.png\"\n default_prompt: \"Edit or review this .docx file and return the updated file plus a concise change summary.\"\n" }, { "path": "skills/.curated/doc/scripts/render_docx.py", "content": "import argparse\nimport os\nimport re\nimport subprocess\nimport tempfile\nimport xml.etree.ElementTree as ET\nfrom os import makedirs, replace\nfrom os.path import abspath, basename, exists, expanduser, join, splitext\nfrom shutil import which\nimport sys\nfrom typing import Sequence, cast\nfrom zipfile import ZipFile\n\nfrom pdf2image import convert_from_path, pdfinfo_from_path\n\nTWIPS_PER_INCH: int = 1440\n\n\ndef ensure_system_tools() -> None:\n missing: list[str] = []\n for tool in (\"soffice\", \"pdftoppm\"):\n if which(tool) is None:\n missing.append(tool)\n if missing:\n tools = \", \".join(missing)\n raise RuntimeError(\n f\"Missing required system tool(s): {tools}. Install LibreOffice and Poppler, then retry.\"\n )\n\n\ndef calc_dpi_via_ooxml_docx(input_path: str, max_w_px: int, max_h_px: int) -> int:\n \"\"\"Calculate DPI from OOXML `word/document.xml` page size (w:pgSz in twips).\n\n DOCX stores page dimensions in section properties as twips (1/1440 inch).\n We read the first encountered section's page size and compute an isotropic DPI\n that fits within the target max pixel dimensions.\n \"\"\"\n with ZipFile(input_path, \"r\") as zf:\n xml = zf.read(\"word/document.xml\")\n root = ET.fromstring(xml)\n ns = {\"w\": \"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"}\n\n # Common placements: w:body/w:sectPr or w:body/w:p/w:pPr/w:sectPr\n sect_pr = root.find(\".//w:sectPr\", ns)\n if sect_pr is None:\n raise RuntimeError(\"Section properties not found in document.xml\")\n pg_sz = sect_pr.find(\"w:pgSz\", ns)\n if pg_sz is None:\n raise RuntimeError(\"Page size not found in section properties\")\n\n # Values are in twips\n w_twips_str = pg_sz.get(\n \"{http://schemas.openxmlformats.org/wordprocessingml/2006/main}w\"\n ) or pg_sz.get(\"w\")\n h_twips_str = pg_sz.get(\n \"{http://schemas.openxmlformats.org/wordprocessingml/2006/main}h\"\n ) or pg_sz.get(\"h\")\n\n if not w_twips_str or not h_twips_str:\n raise RuntimeError(\"Page size attributes missing in pgSz\")\n\n width_in = int(w_twips_str) / TWIPS_PER_INCH\n height_in = int(h_twips_str) / TWIPS_PER_INCH\n if width_in <= 0 or height_in <= 0:\n raise RuntimeError(\"Invalid page size values in document.xml\")\n return round(min(max_w_px / width_in, max_h_px / height_in))\n\n\ndef calc_dpi_via_pdf(input_path: str, max_w_px: int, max_h_px: int) -> int:\n \"\"\"Convert input to PDF and compute DPI from its page size.\"\"\"\n with tempfile.TemporaryDirectory(prefix=\"soffice_profile_\") as user_profile:\n with tempfile.TemporaryDirectory(prefix=\"soffice_convert_\") as convert_tmp_dir:\n stem = splitext(basename(input_path))[0]\n pdf_path = convert_to_pdf(input_path, user_profile, convert_tmp_dir, stem)\n if not (pdf_path and exists(pdf_path)):\n raise RuntimeError(\"Failed to convert input to PDF for DPI computation.\")\n\n info = pdfinfo_from_path(pdf_path)\n size_val = info.get(\"Page size\")\n if not size_val:\n for k, v in info.items():\n if isinstance(v, str) and \"size\" in k.lower() and \"pts\" in v:\n size_val = v\n break\n if not isinstance(size_val, str):\n raise RuntimeError(\"Failed to read PDF page size for DPI computation.\")\n\n m = re.search(r\"(\\d+)\\s*x\\s*(\\d+)\\s*pts\", size_val)\n if not m:\n raise RuntimeError(\"Unrecognized PDF page size format.\")\n width_pts = int(m.group(1))\n height_pts = int(m.group(2))\n width_in = width_pts / 72.0\n height_in = height_pts / 72.0\n if width_in <= 0 or height_in <= 0:\n raise RuntimeError(\"Invalid PDF page size values.\")\n return round(min(max_w_px / width_in, max_h_px / height_in))\n\n\ndef run_cmd_no_check(cmd: list[str]) -> None:\n subprocess.run(\n cmd,\n check=False,\n stdout=subprocess.DEVNULL,\n stderr=subprocess.DEVNULL,\n env=os.environ.copy(),\n )\n\n\ndef convert_to_pdf(\n doc_path: str,\n user_profile: str,\n convert_tmp_dir: str,\n stem: str,\n) -> str:\n # Try direct DOC(X) -> PDF\n cmd_pdf = [\n \"soffice\",\n \"-env:UserInstallation=file://\" + user_profile,\n \"--invisible\",\n \"--headless\",\n \"--norestore\",\n \"--convert-to\",\n \"pdf\",\n \"--outdir\",\n convert_tmp_dir,\n doc_path,\n ]\n run_cmd_no_check(cmd_pdf)\n\n pdf_path = join(convert_tmp_dir, f\"{stem}.pdf\")\n if exists(pdf_path):\n return pdf_path\n\n # Fallback: DOCX -> ODT, then ODT -> PDF\n cmd_odt = [\n \"soffice\",\n \"-env:UserInstallation=file://\" + user_profile,\n \"--invisible\",\n \"--headless\",\n \"--norestore\",\n \"--convert-to\",\n \"odt\",\n \"--outdir\",\n convert_tmp_dir,\n doc_path,\n ]\n run_cmd_no_check(cmd_odt)\n\n odt_path = join(convert_tmp_dir, f\"{stem}.odt\")\n\n if exists(odt_path):\n cmd_odt_pdf = [\n \"soffice\",\n \"-env:UserInstallation=file://\" + user_profile,\n \"--invisible\",\n \"--headless\",\n \"--norestore\",\n \"--convert-to\",\n \"pdf\",\n \"--outdir\",\n convert_tmp_dir,\n odt_path,\n ]\n run_cmd_no_check(cmd_odt_pdf)\n if exists(pdf_path):\n return pdf_path\n\n return \"\"\n\n\ndef rasterize(\n doc_path: str,\n out_dir: str,\n dpi: int,\n) -> Sequence[str]:\n \"\"\"Rasterise DOCX (or similar) to images placed in out_dir and return their paths.\n\n Images are named as page-. with pages starting at 1.\n \"\"\"\n makedirs(out_dir, exist_ok=True)\n doc_path = abspath(doc_path)\n stem = splitext(basename(doc_path))[0]\n\n # Use a unique user profile to avoid LibreOffice profile lock when running concurrently\n with tempfile.TemporaryDirectory(prefix=\"soffice_profile_\") as user_profile:\n # Write conversion outputs into a temp directory to avoid any IO oddities\n with tempfile.TemporaryDirectory(prefix=\"soffice_convert_\") as convert_tmp_dir:\n pdf_path = convert_to_pdf(\n doc_path,\n user_profile,\n convert_tmp_dir,\n stem,\n )\n\n if not pdf_path or not exists(pdf_path):\n raise RuntimeError(\n \"Failed to produce PDF for rasterization (direct and ODT fallback).\"\n )\n paths_raw = cast(\n list[str],\n convert_from_path(\n pdf_path,\n dpi=dpi,\n fmt=\"png\",\n thread_count=8,\n output_folder=out_dir,\n paths_only=True,\n output_file=\"page\",\n ),\n )\n\n # Rename convert_from_path's output format f'page{thread_id:04d}-{page_num:02d}.' to 'page-.'\n pages: list[tuple[int, str]] = []\n for src_path in paths_raw:\n base = splitext(basename(src_path))[0]\n page_num_str = base.split(\"-\")[-1]\n page_num = int(page_num_str)\n dst_path = join(out_dir, f\"page-{page_num}.png\")\n replace(src_path, dst_path)\n pages.append((page_num, dst_path))\n pages.sort(key=lambda t: t[0])\n final_paths = [path for _, path in pages]\n return final_paths\n\n\ndef main() -> None:\n parser = argparse.ArgumentParser(description=\"Render DOCX-like file to PNG images.\")\n parser.add_argument(\n \"input_path\",\n type=str,\n help=\"Path to the input DOCX file (or compatible).\",\n )\n parser.add_argument(\n \"--output_dir\",\n type=str,\n default=None,\n help=(\n \"Output directory for the rendered images. \"\n \"Defaults to a folder next to the input named after the input file (without extension).\"\n ),\n )\n parser.add_argument(\n \"--width\",\n type=int,\n default=1600,\n help=(\n \"Approximate maximum width in pixels after isotropic scaling (default 1600). \"\n \"The actual value may exceed slightly.\"\n ),\n )\n parser.add_argument(\n \"--height\",\n type=int,\n default=2000,\n help=(\n \"Approximate maximum height in pixels after isotropic scaling (default 2000). \"\n \"The actual value may exceed slightly.\"\n ),\n )\n parser.add_argument(\n \"--dpi\",\n type=int,\n default=None,\n help=(\"Override computed DPI. If provided, skips DOCX/PDF-based DPI calculation.\"),\n )\n args = parser.parse_args()\n\n try:\n ensure_system_tools()\n\n input_path = abspath(expanduser(args.input_path))\n out_dir = (\n abspath(expanduser(args.output_dir)) if args.output_dir else splitext(input_path)[0]\n )\n\n if args.dpi is not None:\n dpi = int(args.dpi)\n else:\n try:\n if input_path.lower().endswith((\".docx\", \".docm\", \".dotx\", \".dotm\")):\n dpi = calc_dpi_via_ooxml_docx(input_path, args.width, args.height)\n else:\n raise RuntimeError(\"Skip OOXML DPI; not a DOCX container\")\n except Exception:\n dpi = calc_dpi_via_pdf(input_path, args.width, args.height)\n\n rasterize(input_path, out_dir, dpi)\n print(\"Pages rendered to \" + out_dir)\n except RuntimeError as exc:\n print(f\"Error: {exc}\", file=sys.stderr)\n raise SystemExit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "skills/.curated/figma/LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n" }, { "path": "skills/.curated/figma/SKILL.md", "content": "---\nname: figma\ndescription: Use the Figma MCP server to fetch design context, screenshots, variables, and assets from Figma, and to translate Figma nodes into production code. Trigger when a task involves Figma URLs, node IDs, design-to-code implementation, or Figma MCP setup and troubleshooting.\n---\n\n# Figma MCP\n\nUse the Figma MCP server for Figma-driven implementation. For setup and debugging details (env vars, config, verification), see `references/figma-mcp-config.md`.\n\n## Figma MCP Integration Rules\nThese rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change.\n\n### Required flow (do not skip)\n1. Run get_design_context first to fetch the structured representation for the exact node(s).\n2. If the response is too large or truncated, run get_metadata to get the high-level node map and then re-fetch only the required node(s) with get_design_context.\n3. Run get_screenshot for a visual reference of the node variant being implemented.\n4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation.\n5. Translate the output (usually React + Tailwind) into this project's conventions, styles and framework. Reuse the project's color tokens, components, and typography wherever possible.\n6. Validate against Figma for 1:1 look and behavior before marking complete.\n\n### Implementation rules\n- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style.\n- Replace Tailwind utility classes with the project's preferred utilities/design-system tokens when applicable.\n- Reuse existing components (e.g., buttons, inputs, typography, icon wrappers) instead of duplicating functionality.\n- Use the project's color system, typography scale, and spacing tokens consistently.\n- Respect existing routing, state management, and data-fetch patterns already adopted in the repo.\n- Strive for 1:1 visual parity with the Figma design. When conflicts arise, prefer design-system tokens and adjust spacing or sizes minimally to match visuals.\n- Validate the final UI against the Figma screenshot for both look and behavior.\n\n### Asset handling\n- The Figma MCP Server provides an assets endpoint which can serve image and SVG assets.\n- IMPORTANT: If the Figma MCP Server returns a localhost source for an image or an SVG, use that image or SVG source directly.\n- IMPORTANT: DO NOT import/add new icon packages, all the assets should be in the Figma payload.\n- IMPORTANT: do NOT use or create placeholders if a localhost source is provided.\n\n### Link-based prompting\n- The server is link-based: copy the Figma frame/layer link and give that URL to the MCP client when asking for implementation help.\n- The client cannot browse the URL but extracts the node ID from the link; always ensure the link points to the exact node/variant you want.\n\n## References\n- `references/figma-mcp-config.md` — setup, verification, troubleshooting, and link-based usage reminders.\n- `references/figma-tools-and-prompts.md` — tool catalog and prompt patterns for selecting frameworks/components and fetching metadata.\n" }, { "path": "skills/.curated/figma/agents/openai.yaml", "content": "interface:\n display_name: \"Figma\"\n short_description: \"Use Figma MCP for design-to-code work\"\n icon_small: \"./assets/figma-small.svg\"\n icon_large: \"./assets/figma.png\"\n default_prompt: \"Use Figma MCP to inspect the target design and translate it into implementable UI decisions.\"\n\ndependencies:\n tools:\n - type: \"mcp\"\n value: \"figma\"\n description: \"Figma MCP server\"\n transport: \"streamable_http\"\n url: \"https://mcp.figma.com/mcp\"\n" }, { "path": "skills/.curated/figma/references/figma-mcp-config.md", "content": "# Figma MCP config reference\n\nUse this snippet to register the Figma MCP server in `~/.codex/config.toml` as a streamable HTTP server with bearer auth pulled from your env.\n\n```toml\n[mcp_servers.figma]\nurl = \"https://mcp.figma.com/mcp\"\nbearer_token_env_var = \"FIGMA_OAUTH_TOKEN\"\nhttp_headers = { \"X-Figma-Region\" = \"us-east-1\" }\n```\n\n## Notes and options\n- The bearer token must be available as `FIGMA_OAUTH_TOKEN` in the environment that launches Codex.\n- Keep the region header aligned with your Figma region. If your org uses another region, update `X-Figma-Region` consistently.\n- OAuth on streamable HTTP requires the RMCP client: set `[features].rmcp_client = true` (or `experimental_use_rmcp_client = true` on older builds) at the top level of `config.toml`.\n- Optional per-server timeouts: `startup_timeout_sec` (default 10) and `tool_timeout_sec` (default 60) can be set inside `[mcp_servers.figma]` if needed.\n\n## Env var setup (if missing)\n- One-time set for current shell: `export FIGMA_OAUTH_TOKEN=\"\"`\n- Persist for future sessions: add the export line to your shell profile (e.g., `~/.zshrc` or `~/.bashrc`), then restart the shell or your IDE.\n- Verify before launching Codex: `echo $FIGMA_OAUTH_TOKEN` should print a non-empty token.\n\n## Setup + verification checklist\n- Add the snippet above to `~/.codex/config.toml` under `[mcp_servers.figma]`, and enable `[features].rmcp_client = true` (or `experimental_use_rmcp_client = true` on older releases).\n- Restart Codex (CLI/IDE) after updating config and env vars.\n- Ask Codex to list Figma tools or run a simple call to confirm the server is reachable.\n\n## Troubleshooting\n- Token not picked up: Export `FIGMA_OAUTH_TOKEN` in the same shell that launches Codex, or add it to your shell profile and restart.\n- OAuth errors: Verify `rmcp_client` is enabled and the bearer token is valid. Tokens copied from Figma should not include surrounding quotes.\n- Network/headers: Keep the `X-Figma-Region` header; if your org uses another region, update the header consistently across config and requests.\n\n## Usage reminders\n- The server is link-based: copy the Figma frame or layer link, then ask the MCP client to implement that URL. The client will extract the node ID from the link (it does not browse the page).\n- If output feels generic, restate the project-specific rules from the main skill and ensure you follow the required flow (get_design_context → get_metadata if needed → get_screenshot).\n" }, { "path": "skills/.curated/figma/references/figma-tools-and-prompts.md", "content": "# Figma MCP tools and prompt patterns\n\nQuick reference for the Figma MCP toolset, when to use each tool, and prompt examples to steer output toward your stack.\n\n## Core tools\n- `get_design_context` (Figma Design, Figma Make): Primary tool. Returns structured design data and default React + Tailwind code. Selection-based prompting works on desktop; the remote server uses a frame/layer link to extract the node ID.\n- `get_variable_defs` (Figma Design): Lists variables/styles (colors, spacing, typography) used in the selection. Useful to align with tokens.\n- `get_metadata` (Figma Design): Sparse XML outline of layer IDs/names/types/positions/sizes. Use before re-calling `get_design_context` on large nodes to avoid truncation.\n- `get_screenshot` (Figma Design, FigJam): Screenshot of the selection for visual fidelity checks.\n- `get_figjam` (FigJam): XML + screenshots for FigJam diagrams (architecture, flows).\n- `create_design_system_rules` (no file context): Generates a rule file with design-to-code guidance for your stack. Save it where the agent can read it.\n- `get_code_connect_map` (Figma Design): Returns mapping of Figma node IDs to code components (`codeConnectSrc`, `codeConnectName`). Use to reuse existing components.\n- `add_code_connect_map` (Figma Design): Adds/updates a mapping between a Figma node and a code component to improve reuse.\n- `get_strategy_for_mapping` (alpha, local only): Figma-prompted tool to decide mapping strategy for connecting a node to a code component.\n- `send_get_strategy_response` (alpha, local only): Sends the response after `get_strategy_for_mapping`.\n- `whoami` (remote only): Returns the authenticated Figma user identity (email, plans, seat types).\n\n## Prompt patterns (design context)\n- Change framework: “generate my Figma selection in Vue” or “in plain HTML + CSS” or “for iOS”.\n- Use my components: “generate my Figma selection using components from `src/components/ui`”.\n- Combine: “generate my Figma selection using components from `src/ui` and style with Tailwind”.\n- Note: On the remote server, selection-based prompting requires a frame/layer link; the server extracts the node ID from the URL.\n\n## Prompt patterns (variables/styles)\n- “get the variables used in my Figma selection”\n- “what color and spacing variables are used in my Figma selection?”\n- “list the variable names and their values used in my Figma selection”\n\n## Prompt patterns (code connect)\n- “show the code connect map for this selection”\n- “map this node to `src/components/ui/Button.tsx` with name `Button`”\n\n## Best-practice flow reminder\nUse `get_design_context` → (optionally `get_metadata` for large nodes) → `get_screenshot`, and keep project rules from `SKILL.md` in mind when applying the generated output.\n" }, { "path": "skills/.curated/figma-implement-design/LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n" }, { "path": "skills/.curated/figma-implement-design/SKILL.md", "content": "---\nname: \"figma-implement-design\"\ndescription: \"Translate Figma nodes into production-ready code with 1:1 visual fidelity using the Figma MCP workflow (design context, screenshots, assets, and project-convention translation). Trigger when the user provides Figma URLs or node IDs, or asks to implement designs or components that must match Figma specs. Requires a working Figma MCP server connection.\"\n---\n\n\n# Implement Design\n\n## Overview\n\nThis skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.\n\n## Prerequisites\n\n- Figma MCP server must be connected and accessible\n- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`\n - `:fileKey` is the file key\n - `1-2` is the node ID (the specific component or frame to implement)\n- **OR** when using `figma-desktop` MCP: User can select a node directly in the Figma desktop app (no URL required)\n- Project should have an established design system or component library (preferred)\n\n## Required Workflow\n\n**Follow these steps in order. Do not skip steps.**\n\n### Step 0: Set up Figma MCP (if not already configured)\n\nIf any MCP call fails because Figma MCP is not connected, pause and set it up:\n\n1. Add the Figma MCP:\n - `codex mcp add figma --url https://mcp.figma.com/mcp`\n2. Enable remote MCP client:\n - Set `[features].rmcp_client = true` in `config.toml` **or** run `codex --enable rmcp_client`\n3. Log in with OAuth:\n - `codex mcp login figma`\n\nAfter successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.\n\n### Step 1: Get Node ID\n\n#### Option A: Parse from Figma URL\n\nWhen the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.\n\n**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`\n\n**Extract:**\n\n- **File key:** `:fileKey` (the segment after `/design/`)\n- **Node ID:** `1-2` (the value of the `node-id` query parameter)\n\n**Note:** When using the local desktop MCP (`figma-desktop`), `fileKey` is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only `nodeId` is needed.\n\n**Example:**\n\n- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`\n- File key: `kL9xQn2VwM8pYrTb4ZcHjF`\n- Node ID: `42-15`\n\n#### Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)\n\nWhen using the `figma-desktop` MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.\n\n**Note:** Selection-based prompting only works with the `figma-desktop` MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.\n\n### Step 2: Fetch Design Context\n\nRun `get_design_context` with the extracted file key and node ID.\n\n```\nget_design_context(fileKey=\":fileKey\", nodeId=\"1-2\")\n```\n\nThis provides the structured data including:\n\n- Layout properties (Auto Layout, constraints, sizing)\n- Typography specifications\n- Color values and design tokens\n- Component structure and variants\n- Spacing and padding values\n\n**If the response is too large or truncated:**\n\n1. Run `get_metadata(fileKey=\":fileKey\", nodeId=\"1-2\")` to get the high-level node map\n2. Identify the specific child nodes needed from the metadata\n3. Fetch individual child nodes with `get_design_context(fileKey=\":fileKey\", nodeId=\":childNodeId\")`\n\n### Step 3: Capture Visual Reference\n\nRun `get_screenshot` with the same file key and node ID for a visual reference.\n\n```\nget_screenshot(fileKey=\":fileKey\", nodeId=\"1-2\")\n```\n\nThis screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.\n\n### Step 4: Download Required Assets\n\nDownload any assets (images, icons, SVGs) returned by the Figma MCP server.\n\n**IMPORTANT:** Follow these asset rules:\n\n- If the Figma MCP server returns a `localhost` source for an image or SVG, use that source directly\n- DO NOT import or add new icon packages - all assets should come from the Figma payload\n- DO NOT use or create placeholders if a `localhost` source is provided\n- Assets are served through the Figma MCP server's built-in assets endpoint\n\n### Step 5: Translate to Project Conventions\n\nTranslate the Figma output into this project's framework, styles, and conventions.\n\n**Key principles:**\n\n- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style\n- Replace Tailwind utility classes with the project's preferred utilities or design system tokens\n- Reuse existing components (buttons, inputs, typography, icon wrappers) instead of duplicating functionality\n- Use the project's color system, typography scale, and spacing tokens consistently\n- Respect existing routing, state management, and data-fetch patterns\n\n### Step 6: Achieve 1:1 Visual Parity\n\nStrive for pixel-perfect visual parity with the Figma design.\n\n**Guidelines:**\n\n- Prioritize Figma fidelity to match designs exactly\n- Avoid hardcoded values - use design tokens from Figma where available\n- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals\n- Follow WCAG requirements for accessibility\n- Add component documentation as needed\n\n### Step 7: Validate Against Figma\n\nBefore marking complete, validate the final UI against the Figma screenshot.\n\n**Validation checklist:**\n\n- [ ] Layout matches (spacing, alignment, sizing)\n- [ ] Typography matches (font, size, weight, line height)\n- [ ] Colors match exactly\n- [ ] Interactive states work as designed (hover, active, disabled)\n- [ ] Responsive behavior follows Figma constraints\n- [ ] Assets render correctly\n- [ ] Accessibility standards met\n\n## Implementation Rules\n\n### Component Organization\n\n- Place UI components in the project's designated design system directory\n- Follow the project's component naming conventions\n- Avoid inline styles unless truly necessary for dynamic values\n\n### Design System Integration\n\n- ALWAYS use components from the project's design system when possible\n- Map Figma design tokens to project design tokens\n- When a matching component exists, extend it rather than creating a new one\n- Document any new components added to the design system\n\n### Code Quality\n\n- Avoid hardcoded values - extract to constants or design tokens\n- Keep components composable and reusable\n- Add TypeScript types for component props\n- Include JSDoc comments for exported components\n\n## Examples\n\n### Example 1: Implementing a Button Component\n\nUser says: \"Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15\"\n\n**Actions:**\n\n1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`\n2. Run `get_design_context(fileKey=\"kL9xQn2VwM8pYrTb4ZcHjF\", nodeId=\"42-15\")`\n3. Run `get_screenshot(fileKey=\"kL9xQn2VwM8pYrTb4ZcHjF\", nodeId=\"42-15\")` for visual reference\n4. Download any button icons from the assets endpoint\n5. Check if project has existing button component\n6. If yes, extend it with new variant; if no, create new component using project conventions\n7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)\n8. Validate against screenshot for padding, border radius, typography\n\n**Result:** Button component matching Figma design, integrated with project design system.\n\n### Example 2: Building a Dashboard Layout\n\nUser says: \"Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5\"\n\n**Actions:**\n\n1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`\n2. Run `get_metadata(fileKey=\"pR8mNv5KqXzGwY2JtCfL4D\", nodeId=\"10-5\")` to understand the page structure\n3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs\n4. Run `get_design_context(fileKey=\"pR8mNv5KqXzGwY2JtCfL4D\", nodeId=\":childNodeId\")` for each major section\n5. Run `get_screenshot(fileKey=\"pR8mNv5KqXzGwY2JtCfL4D\", nodeId=\"10-5\")` for the full page\n6. Download all assets (logos, icons, charts)\n7. Build layout using project's layout primitives\n8. Implement each section using existing components where possible\n9. Validate responsive behavior against Figma constraints\n\n**Result:** Complete dashboard matching Figma design with responsive layout.\n\n## Best Practices\n\n### Always Start with Context\n\nNever implement based on assumptions. Always fetch `get_design_context` and `get_screenshot` first.\n\n### Incremental Validation\n\nValidate frequently during implementation, not just at the end. This catches issues early.\n\n### Document Deviations\n\nIf you must deviate from the Figma design (e.g., for accessibility or technical constraints), document why in code comments.\n\n### Reuse Over Recreation\n\nAlways check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.\n\n### Design System First\n\nWhen in doubt, prefer the project's design system patterns over literal Figma translation.\n\n## Common Issues and Solutions\n\n### Issue: Figma output is truncated\n\n**Cause:** The design is too complex or has too many nested layers to return in a single response.\n**Solution:** Use `get_metadata` to get the node structure, then fetch specific nodes individually with `get_design_context`.\n\n### Issue: Design doesn't match after implementation\n\n**Cause:** Visual discrepancies between the implemented code and the original Figma design.\n**Solution:** Compare side-by-side with the screenshot from Step 3. Check spacing, colors, and typography values in the design context data.\n\n### Issue: Assets not loading\n\n**Cause:** The Figma MCP server's assets endpoint is not accessible or the URLs are being modified.\n**Solution:** Verify the Figma MCP server's assets endpoint is accessible. The server serves assets at `localhost` URLs. Use these directly without modification.\n\n### Issue: Design token values differ from Figma\n\n**Cause:** The project's design system tokens have different values than those specified in the Figma design.\n**Solution:** When project tokens differ from Figma values, prefer project tokens for consistency but adjust spacing/sizing to maintain visual fidelity.\n\n## Understanding Design Implementation\n\nThe Figma implementation workflow establishes a reliable process for translating designs to code:\n\n**For designers:** Confidence that implementations will match their designs with pixel-perfect accuracy.\n**For developers:** A structured approach that eliminates guesswork and reduces back-and-forth revisions.\n**For teams:** Consistent, high-quality implementations that maintain design system integrity.\n\nBy following this workflow, you ensure that every Figma design is implemented with the same level of care and attention to detail.\n\n## Additional Resources\n\n- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)\n- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)\n- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)\n" }, { "path": "skills/.curated/figma-implement-design/agents/openai.yaml", "content": "interface:\n display_name: \"Figma Implement Design\"\n short_description: \"Turn Figma designs into production-ready code\"\n icon_small: \"./assets/figma-small.svg\"\n icon_large: \"./assets/figma.png\"\n default_prompt: \"Implement this Figma design in this codebase, matching layout, states, and responsive behavior.\"\n\ndependencies:\n tools:\n - type: \"mcp\"\n value: \"figma\"\n description: \"Figma MCP server\"\n transport: \"streamable_http\"\n url: \"https://mcp.figma.com/mcp\"\n" }, { "path": "skills/.curated/gh-address-comments/LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "skills/.curated/gh-address-comments/SKILL.md", "content": "---\nname: gh-address-comments\ndescription: Help address review/issue comments on the open GitHub PR for the current branch using gh CLI; verify gh auth first and prompt the user to authenticate if not logged in.\nmetadata:\n short-description: Address comments in a GitHub PR review\n---\n\n# PR Comment Handler\n\nGuide to find the open PR for the current branch and address its comments with gh CLI. Run all `gh` commands with elevated network access.\n\nPrereq: ensure `gh` is authenticated (for example, run `gh auth login` once), then run `gh auth status` with escalated permissions (include workflow/repo scopes) so `gh` commands succeed. If sandboxing blocks `gh auth status`, rerun it with `sandbox_permissions=require_escalated`.\n\n## 1) Inspect comments needing attention\n- Run scripts/fetch_comments.py which will print out all the comments and review threads on the PR\n\n## 2) Ask the user for clarification\n- Number all the review threads and comments and provide a short summary of what would be required to apply a fix for it\n- Ask the user which numbered comments should be addressed\n\n## 3) If user chooses comments\n- Apply fixes for the selected comments\n\nNotes:\n- If gh hits auth/rate issues mid-run, prompt the user to re-authenticate with `gh auth login`, then retry.\n" }, { "path": "skills/.curated/gh-address-comments/agents/openai.yaml", "content": "interface:\n display_name: \"GitHub Address Comments\"\n short_description: Address comments in a GitHub PR review\"\n icon_small: \"./assets/github-small.svg\"\n icon_large: \"./assets/github.png\"\n default_prompt: \"Address all actionable GitHub PR review comments in this branch and summarize the updates.\"\n" }, { "path": "skills/.curated/gh-address-comments/scripts/fetch_comments.py", "content": "#!/usr/bin/env python3\n\"\"\"\nFetch all PR conversation comments + reviews + review threads (inline threads)\nfor the PR associated with the current git branch, by shelling out to:\n\n gh api graphql\n\nRequires:\n - `gh auth login` already set up\n - current branch has an associated (open) PR\n\nUsage:\n python fetch_comments.py > pr_comments.json\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport subprocess\nimport sys\nfrom typing import Any\n\nQUERY = \"\"\"\\\nquery(\n $owner: String!,\n $repo: String!,\n $number: Int!,\n $commentsCursor: String,\n $reviewsCursor: String,\n $threadsCursor: String\n) {\n repository(owner: $owner, name: $repo) {\n pullRequest(number: $number) {\n number\n url\n title\n state\n\n # Top-level \"Conversation\" comments (issue comments on the PR)\n comments(first: 100, after: $commentsCursor) {\n pageInfo { hasNextPage endCursor }\n nodes {\n id\n body\n createdAt\n updatedAt\n author { login }\n }\n }\n\n # Review submissions (Approve / Request changes / Comment), with body if present\n reviews(first: 100, after: $reviewsCursor) {\n pageInfo { hasNextPage endCursor }\n nodes {\n id\n state\n body\n submittedAt\n author { login }\n }\n }\n\n # Inline review threads (grouped), includes resolved state\n reviewThreads(first: 100, after: $threadsCursor) {\n pageInfo { hasNextPage endCursor }\n nodes {\n id\n isResolved\n isOutdated\n path\n line\n diffSide\n startLine\n startDiffSide\n originalLine\n originalStartLine\n resolvedBy { login }\n comments(first: 100) {\n nodes {\n id\n body\n createdAt\n updatedAt\n author { login }\n }\n }\n }\n }\n }\n }\n}\n\"\"\"\n\n\ndef _run(cmd: list[str], stdin: str | None = None) -> str:\n p = subprocess.run(cmd, input=stdin, capture_output=True, text=True)\n if p.returncode != 0:\n raise RuntimeError(f\"Command failed: {' '.join(cmd)}\\n{p.stderr}\")\n return p.stdout\n\n\ndef _run_json(cmd: list[str], stdin: str | None = None) -> dict[str, Any]:\n out = _run(cmd, stdin=stdin)\n try:\n return json.loads(out)\n except json.JSONDecodeError as e:\n raise RuntimeError(f\"Failed to parse JSON from command output: {e}\\nRaw:\\n{out}\") from e\n\n\ndef _ensure_gh_authenticated() -> None:\n try:\n _run([\"gh\", \"auth\", \"status\"])\n except RuntimeError:\n print(\"run `gh auth login` to authenticate the GitHub CLI\", file=sys.stderr)\n raise RuntimeError(\"gh auth status failed; run `gh auth login` to authenticate the GitHub CLI\") from None\n\n\ndef gh_pr_view_json(fields: str) -> dict[str, Any]:\n # fields is a comma-separated list like: \"number,headRepositoryOwner,headRepository\"\n return _run_json([\"gh\", \"pr\", \"view\", \"--json\", fields])\n\n\ndef get_current_pr_ref() -> tuple[str, str, int]:\n \"\"\"\n Resolve the PR for the current branch (whatever gh considers associated).\n Works for cross-repo PRs too, by reading head repository owner/name.\n \"\"\"\n pr = gh_pr_view_json(\"number,headRepositoryOwner,headRepository\")\n owner = pr[\"headRepositoryOwner\"][\"login\"]\n repo = pr[\"headRepository\"][\"name\"]\n number = int(pr[\"number\"])\n return owner, repo, number\n\n\ndef gh_api_graphql(\n owner: str,\n repo: str,\n number: int,\n comments_cursor: str | None = None,\n reviews_cursor: str | None = None,\n threads_cursor: str | None = None,\n) -> dict[str, Any]:\n \"\"\"\n Call `gh api graphql` using -F variables, avoiding JSON blobs with nulls.\n Query is passed via stdin using query=@- to avoid shell newline/quoting issues.\n \"\"\"\n cmd = [\n \"gh\",\n \"api\",\n \"graphql\",\n \"-F\",\n \"query=@-\",\n \"-F\",\n f\"owner={owner}\",\n \"-F\",\n f\"repo={repo}\",\n \"-F\",\n f\"number={number}\",\n ]\n if comments_cursor:\n cmd += [\"-F\", f\"commentsCursor={comments_cursor}\"]\n if reviews_cursor:\n cmd += [\"-F\", f\"reviewsCursor={reviews_cursor}\"]\n if threads_cursor:\n cmd += [\"-F\", f\"threadsCursor={threads_cursor}\"]\n\n return _run_json(cmd, stdin=QUERY)\n\n\ndef fetch_all(owner: str, repo: str, number: int) -> dict[str, Any]:\n conversation_comments: list[dict[str, Any]] = []\n reviews: list[dict[str, Any]] = []\n review_threads: list[dict[str, Any]] = []\n\n comments_cursor: str | None = None\n reviews_cursor: str | None = None\n threads_cursor: str | None = None\n\n pr_meta: dict[str, Any] | None = None\n\n while True:\n payload = gh_api_graphql(\n owner=owner,\n repo=repo,\n number=number,\n comments_cursor=comments_cursor,\n reviews_cursor=reviews_cursor,\n threads_cursor=threads_cursor,\n )\n\n if \"errors\" in payload and payload[\"errors\"]:\n raise RuntimeError(f\"GitHub GraphQL errors:\\n{json.dumps(payload['errors'], indent=2)}\")\n\n pr = payload[\"data\"][\"repository\"][\"pullRequest\"]\n if pr_meta is None:\n pr_meta = {\n \"number\": pr[\"number\"],\n \"url\": pr[\"url\"],\n \"title\": pr[\"title\"],\n \"state\": pr[\"state\"],\n \"owner\": owner,\n \"repo\": repo,\n }\n\n c = pr[\"comments\"]\n r = pr[\"reviews\"]\n t = pr[\"reviewThreads\"]\n\n conversation_comments.extend(c.get(\"nodes\") or [])\n reviews.extend(r.get(\"nodes\") or [])\n review_threads.extend(t.get(\"nodes\") or [])\n\n comments_cursor = c[\"pageInfo\"][\"endCursor\"] if c[\"pageInfo\"][\"hasNextPage\"] else None\n reviews_cursor = r[\"pageInfo\"][\"endCursor\"] if r[\"pageInfo\"][\"hasNextPage\"] else None\n threads_cursor = t[\"pageInfo\"][\"endCursor\"] if t[\"pageInfo\"][\"hasNextPage\"] else None\n\n if not (comments_cursor or reviews_cursor or threads_cursor):\n break\n\n assert pr_meta is not None\n return {\n \"pull_request\": pr_meta,\n \"conversation_comments\": conversation_comments,\n \"reviews\": reviews,\n \"review_threads\": review_threads,\n }\n\n\ndef main() -> None:\n _ensure_gh_authenticated()\n owner, repo, number = get_current_pr_ref()\n result = fetch_all(owner, repo, number)\n print(json.dumps(result, indent=2))\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "skills/.curated/gh-fix-ci/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don\\'t include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/gh-fix-ci/SKILL.md", "content": "---\nname: \"gh-fix-ci\"\ndescription: \"Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions; use `gh` to inspect checks and logs, summarize failure context, draft a fix plan, and implement only after explicit approval. Treat external providers (for example Buildkite) as out of scope and report only the details URL.\"\n---\n\n\n# Gh Pr Checks Plan Fix\n\n## Overview\n\nUse gh to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure snippet, then propose a fix plan and implement after explicit approval.\n- If a plan-oriented skill (for example `create-plan`) is available, use it; otherwise draft a concise plan inline and request approval before implementing.\n\nPrereq: authenticate with the standard GitHub CLI once (for example, run `gh auth login`), then confirm with `gh auth status` (repo + workflow scopes are typically required).\n\n## Inputs\n\n- `repo`: path inside the repo (default `.`)\n- `pr`: PR number or URL (optional; defaults to current branch PR)\n- `gh` authentication for the repo host\n\n## Quick start\n\n- `python \"/scripts/inspect_pr_checks.py\" --repo \".\" --pr \"\"`\n- Add `--json` if you want machine-friendly output for summarization.\n\n## Workflow\n\n1. Verify gh authentication.\n - Run `gh auth status` in the repo.\n - If unauthenticated, ask the user to run `gh auth login` (ensuring repo + workflow scopes) before proceeding.\n2. Resolve the PR.\n - Prefer the current branch PR: `gh pr view --json number,url`.\n - If the user provides a PR number or URL, use that directly.\n3. Inspect failing checks (GitHub Actions only).\n - Preferred: run the bundled script (handles gh field drift and job-log fallbacks):\n - `python \"/scripts/inspect_pr_checks.py\" --repo \".\" --pr \"\"`\n - Add `--json` for machine-friendly output.\n - Manual fallback:\n - `gh pr checks --json name,state,bucket,link,startedAt,completedAt,workflow`\n - If a field is rejected, rerun with the available fields reported by `gh`.\n - For each failing check, extract the run id from `detailsUrl` and run:\n - `gh run view --json name,workflowName,conclusion,status,url,event,headBranch,headSha`\n - `gh run view --log`\n - If the run log says it is still in progress, fetch job logs directly:\n - `gh api \"/repos///actions/jobs//logs\" > \"\"`\n4. Scope non-GitHub Actions checks.\n - If `detailsUrl` is not a GitHub Actions run, label it as external and only report the URL.\n - Do not attempt Buildkite or other providers; keep the workflow lean.\n5. Summarize failures for the user.\n - Provide the failing check name, run URL (if any), and a concise log snippet.\n - Call out missing logs explicitly.\n6. Create a plan.\n - Use the `create-plan` skill to draft a concise plan and request approval.\n7. Implement after approval.\n - Apply the approved plan, summarize diffs/tests, and ask about opening a PR.\n8. Recheck status.\n - After changes, suggest re-running the relevant tests and `gh pr checks` to confirm.\n\n## Bundled Resources\n\n### scripts/inspect_pr_checks.py\n\nFetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet. Exits non-zero when failures remain so it can be used in automation.\n\nUsage examples:\n- `python \"/scripts/inspect_pr_checks.py\" --repo \".\" --pr \"123\"`\n- `python \"/scripts/inspect_pr_checks.py\" --repo \".\" --pr \"https://github.com/org/repo/pull/123\" --json`\n- `python \"/scripts/inspect_pr_checks.py\" --repo \".\" --max-lines 200 --context 40`\n" }, { "path": "skills/.curated/gh-fix-ci/agents/openai.yaml", "content": "interface:\n display_name: \"GitHub Fix CI\"\n short_description: \"Debug failing GitHub Actions CI\"\n icon_small: \"./assets/github-small.svg\"\n icon_large: \"./assets/github.png\"\n default_prompt: \"Inspect failing GitHub Actions checks in this repo, summarize root cause, and propose a focused fix plan.\"\n" }, { "path": "skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.py", "content": "#!/usr/bin/env python3\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport re\nimport subprocess\nimport sys\nfrom pathlib import Path\nfrom shutil import which\nfrom typing import Any, Iterable, Sequence\n\nFAILURE_CONCLUSIONS = {\n \"failure\",\n \"cancelled\",\n \"timed_out\",\n \"action_required\",\n}\n\nFAILURE_STATES = {\n \"failure\",\n \"error\",\n \"cancelled\",\n \"timed_out\",\n \"action_required\",\n}\n\nFAILURE_BUCKETS = {\"fail\"}\n\nFAILURE_MARKERS = (\n \"error\",\n \"fail\",\n \"failed\",\n \"traceback\",\n \"exception\",\n \"assert\",\n \"panic\",\n \"fatal\",\n \"timeout\",\n \"segmentation fault\",\n)\n\nDEFAULT_MAX_LINES = 160\nDEFAULT_CONTEXT_LINES = 30\nPENDING_LOG_MARKERS = (\n \"still in progress\",\n \"log will be available when it is complete\",\n)\n\n\nclass GhResult:\n def __init__(self, returncode: int, stdout: str, stderr: str):\n self.returncode = returncode\n self.stdout = stdout\n self.stderr = stderr\n\n\ndef run_gh_command(args: Sequence[str], cwd: Path) -> GhResult:\n process = subprocess.run(\n [\"gh\", *args],\n cwd=cwd,\n text=True,\n capture_output=True,\n )\n return GhResult(process.returncode, process.stdout, process.stderr)\n\n\ndef run_gh_command_raw(args: Sequence[str], cwd: Path) -> tuple[int, bytes, str]:\n process = subprocess.run(\n [\"gh\", *args],\n cwd=cwd,\n capture_output=True,\n )\n stderr = process.stderr.decode(errors=\"replace\")\n return process.returncode, process.stdout, stderr\n\n\ndef parse_args() -> argparse.Namespace:\n parser = argparse.ArgumentParser(\n description=(\n \"Inspect failing GitHub PR checks, fetch GitHub Actions logs, and extract a \"\n \"failure snippet.\"\n ),\n formatter_class=argparse.ArgumentDefaultsHelpFormatter,\n )\n parser.add_argument(\"--repo\", default=\".\", help=\"Path inside the target Git repository.\")\n parser.add_argument(\n \"--pr\", default=None, help=\"PR number or URL (defaults to current branch PR).\"\n )\n parser.add_argument(\"--max-lines\", type=int, default=DEFAULT_MAX_LINES)\n parser.add_argument(\"--context\", type=int, default=DEFAULT_CONTEXT_LINES)\n parser.add_argument(\"--json\", action=\"store_true\", help=\"Emit JSON instead of text output.\")\n return parser.parse_args()\n\n\ndef main() -> int:\n args = parse_args()\n repo_root = find_git_root(Path(args.repo))\n if repo_root is None:\n print(\"Error: not inside a Git repository.\", file=sys.stderr)\n return 1\n\n if not ensure_gh_available(repo_root):\n return 1\n\n pr_value = resolve_pr(args.pr, repo_root)\n if pr_value is None:\n return 1\n\n checks = fetch_checks(pr_value, repo_root)\n if checks is None:\n return 1\n\n failing = [c for c in checks if is_failing(c)]\n if not failing:\n print(f\"PR #{pr_value}: no failing checks detected.\")\n return 0\n\n results = []\n for check in failing:\n results.append(\n analyze_check(\n check,\n repo_root=repo_root,\n max_lines=max(1, args.max_lines),\n context=max(1, args.context),\n )\n )\n\n if args.json:\n print(json.dumps({\"pr\": pr_value, \"results\": results}, indent=2))\n else:\n render_results(pr_value, results)\n\n return 1\n\n\ndef find_git_root(start: Path) -> Path | None:\n result = subprocess.run(\n [\"git\", \"rev-parse\", \"--show-toplevel\"],\n cwd=start,\n text=True,\n capture_output=True,\n )\n if result.returncode != 0:\n return None\n return Path(result.stdout.strip())\n\n\ndef ensure_gh_available(repo_root: Path) -> bool:\n if which(\"gh\") is None:\n print(\"Error: gh is not installed or not on PATH.\", file=sys.stderr)\n return False\n result = run_gh_command([\"auth\", \"status\"], cwd=repo_root)\n if result.returncode == 0:\n return True\n message = (result.stderr or result.stdout or \"\").strip()\n print(message or \"Error: gh not authenticated.\", file=sys.stderr)\n return False\n\n\ndef resolve_pr(pr_value: str | None, repo_root: Path) -> str | None:\n if pr_value:\n return pr_value\n result = run_gh_command([\"pr\", \"view\", \"--json\", \"number\"], cwd=repo_root)\n if result.returncode != 0:\n message = (result.stderr or result.stdout or \"\").strip()\n print(message or \"Error: unable to resolve PR.\", file=sys.stderr)\n return None\n try:\n data = json.loads(result.stdout or \"{}\")\n except json.JSONDecodeError:\n print(\"Error: unable to parse PR JSON.\", file=sys.stderr)\n return None\n number = data.get(\"number\")\n if not number:\n print(\"Error: no PR number found.\", file=sys.stderr)\n return None\n return str(number)\n\n\ndef fetch_checks(pr_value: str, repo_root: Path) -> list[dict[str, Any]] | None:\n primary_fields = [\"name\", \"state\", \"conclusion\", \"detailsUrl\", \"startedAt\", \"completedAt\"]\n result = run_gh_command(\n [\"pr\", \"checks\", pr_value, \"--json\", \",\".join(primary_fields)],\n cwd=repo_root,\n )\n if result.returncode != 0:\n message = \"\\n\".join(filter(None, [result.stderr, result.stdout])).strip()\n available_fields = parse_available_fields(message)\n if available_fields:\n fallback_fields = [\n \"name\",\n \"state\",\n \"bucket\",\n \"link\",\n \"startedAt\",\n \"completedAt\",\n \"workflow\",\n ]\n selected_fields = [field for field in fallback_fields if field in available_fields]\n if not selected_fields:\n print(\"Error: no usable fields available for gh pr checks.\", file=sys.stderr)\n return None\n result = run_gh_command(\n [\"pr\", \"checks\", pr_value, \"--json\", \",\".join(selected_fields)],\n cwd=repo_root,\n )\n if result.returncode != 0:\n message = (result.stderr or result.stdout or \"\").strip()\n print(message or \"Error: gh pr checks failed.\", file=sys.stderr)\n return None\n else:\n print(message or \"Error: gh pr checks failed.\", file=sys.stderr)\n return None\n try:\n data = json.loads(result.stdout or \"[]\")\n except json.JSONDecodeError:\n print(\"Error: unable to parse checks JSON.\", file=sys.stderr)\n return None\n if not isinstance(data, list):\n print(\"Error: unexpected checks JSON shape.\", file=sys.stderr)\n return None\n return data\n\n\ndef is_failing(check: dict[str, Any]) -> bool:\n conclusion = normalize_field(check.get(\"conclusion\"))\n if conclusion in FAILURE_CONCLUSIONS:\n return True\n state = normalize_field(check.get(\"state\") or check.get(\"status\"))\n if state in FAILURE_STATES:\n return True\n bucket = normalize_field(check.get(\"bucket\"))\n return bucket in FAILURE_BUCKETS\n\n\ndef analyze_check(\n check: dict[str, Any],\n repo_root: Path,\n max_lines: int,\n context: int,\n) -> dict[str, Any]:\n url = check.get(\"detailsUrl\") or check.get(\"link\") or \"\"\n run_id = extract_run_id(url)\n job_id = extract_job_id(url)\n base: dict[str, Any] = {\n \"name\": check.get(\"name\", \"\"),\n \"detailsUrl\": url,\n \"runId\": run_id,\n \"jobId\": job_id,\n }\n\n if run_id is None:\n base[\"status\"] = \"external\"\n base[\"note\"] = \"No GitHub Actions run id detected in detailsUrl.\"\n return base\n\n metadata = fetch_run_metadata(run_id, repo_root)\n log_text, log_error, log_status = fetch_check_log(\n run_id=run_id,\n job_id=job_id,\n repo_root=repo_root,\n )\n\n if log_status == \"pending\":\n base[\"status\"] = \"log_pending\"\n base[\"note\"] = log_error or \"Logs are not available yet.\"\n if metadata:\n base[\"run\"] = metadata\n return base\n\n if log_error:\n base[\"status\"] = \"log_unavailable\"\n base[\"error\"] = log_error\n if metadata:\n base[\"run\"] = metadata\n return base\n\n snippet = extract_failure_snippet(log_text, max_lines=max_lines, context=context)\n base[\"status\"] = \"ok\"\n base[\"run\"] = metadata or {}\n base[\"logSnippet\"] = snippet\n base[\"logTail\"] = tail_lines(log_text, max_lines)\n return base\n\n\ndef extract_run_id(url: str) -> str | None:\n if not url:\n return None\n for pattern in (r\"/actions/runs/(\\d+)\", r\"/runs/(\\d+)\"):\n match = re.search(pattern, url)\n if match:\n return match.group(1)\n return None\n\n\ndef extract_job_id(url: str) -> str | None:\n if not url:\n return None\n match = re.search(r\"/actions/runs/\\d+/job/(\\d+)\", url)\n if match:\n return match.group(1)\n match = re.search(r\"/job/(\\d+)\", url)\n if match:\n return match.group(1)\n return None\n\n\ndef fetch_run_metadata(run_id: str, repo_root: Path) -> dict[str, Any] | None:\n fields = [\n \"conclusion\",\n \"status\",\n \"workflowName\",\n \"name\",\n \"event\",\n \"headBranch\",\n \"headSha\",\n \"url\",\n ]\n result = run_gh_command([\"run\", \"view\", run_id, \"--json\", \",\".join(fields)], cwd=repo_root)\n if result.returncode != 0:\n return None\n try:\n data = json.loads(result.stdout or \"{}\")\n except json.JSONDecodeError:\n return None\n if not isinstance(data, dict):\n return None\n return data\n\n\ndef fetch_check_log(\n run_id: str,\n job_id: str | None,\n repo_root: Path,\n) -> tuple[str, str, str]:\n log_text, log_error = fetch_run_log(run_id, repo_root)\n if not log_error:\n return log_text, \"\", \"ok\"\n\n if is_log_pending_message(log_error) and job_id:\n job_log, job_error = fetch_job_log(job_id, repo_root)\n if job_log:\n return job_log, \"\", \"ok\"\n if job_error and is_log_pending_message(job_error):\n return \"\", job_error, \"pending\"\n if job_error:\n return \"\", job_error, \"error\"\n return \"\", log_error, \"pending\"\n\n if is_log_pending_message(log_error):\n return \"\", log_error, \"pending\"\n\n return \"\", log_error, \"error\"\n\n\ndef fetch_run_log(run_id: str, repo_root: Path) -> tuple[str, str]:\n result = run_gh_command([\"run\", \"view\", run_id, \"--log\"], cwd=repo_root)\n if result.returncode != 0:\n error = (result.stderr or result.stdout or \"\").strip()\n return \"\", error or \"gh run view failed\"\n return result.stdout, \"\"\n\n\ndef fetch_job_log(job_id: str, repo_root: Path) -> tuple[str, str]:\n repo_slug = fetch_repo_slug(repo_root)\n if not repo_slug:\n return \"\", \"Error: unable to resolve repository name for job logs.\"\n endpoint = f\"/repos/{repo_slug}/actions/jobs/{job_id}/logs\"\n returncode, stdout_bytes, stderr = run_gh_command_raw([\"api\", endpoint], cwd=repo_root)\n if returncode != 0:\n message = (stderr or stdout_bytes.decode(errors=\"replace\")).strip()\n return \"\", message or \"gh api job logs failed\"\n if is_zip_payload(stdout_bytes):\n return \"\", \"Job logs returned a zip archive; unable to parse.\"\n return stdout_bytes.decode(errors=\"replace\"), \"\"\n\n\ndef fetch_repo_slug(repo_root: Path) -> str | None:\n result = run_gh_command([\"repo\", \"view\", \"--json\", \"nameWithOwner\"], cwd=repo_root)\n if result.returncode != 0:\n return None\n try:\n data = json.loads(result.stdout or \"{}\")\n except json.JSONDecodeError:\n return None\n name_with_owner = data.get(\"nameWithOwner\")\n if not name_with_owner:\n return None\n return str(name_with_owner)\n\n\ndef normalize_field(value: Any) -> str:\n if value is None:\n return \"\"\n return str(value).strip().lower()\n\n\ndef parse_available_fields(message: str) -> list[str]:\n if \"Available fields:\" not in message:\n return []\n fields: list[str] = []\n collecting = False\n for line in message.splitlines():\n if \"Available fields:\" in line:\n collecting = True\n continue\n if not collecting:\n continue\n field = line.strip()\n if not field:\n continue\n fields.append(field)\n return fields\n\n\ndef is_log_pending_message(message: str) -> bool:\n lowered = message.lower()\n return any(marker in lowered for marker in PENDING_LOG_MARKERS)\n\n\ndef is_zip_payload(payload: bytes) -> bool:\n return payload.startswith(b\"PK\")\n\n\ndef extract_failure_snippet(log_text: str, max_lines: int, context: int) -> str:\n lines = log_text.splitlines()\n if not lines:\n return \"\"\n\n marker_index = find_failure_index(lines)\n if marker_index is None:\n return \"\\n\".join(lines[-max_lines:])\n\n start = max(0, marker_index - context)\n end = min(len(lines), marker_index + context)\n window = lines[start:end]\n if len(window) > max_lines:\n window = window[-max_lines:]\n return \"\\n\".join(window)\n\n\ndef find_failure_index(lines: Sequence[str]) -> int | None:\n for idx in range(len(lines) - 1, -1, -1):\n lowered = lines[idx].lower()\n if any(marker in lowered for marker in FAILURE_MARKERS):\n return idx\n return None\n\n\ndef tail_lines(text: str, max_lines: int) -> str:\n if max_lines <= 0:\n return \"\"\n lines = text.splitlines()\n return \"\\n\".join(lines[-max_lines:])\n\n\ndef render_results(pr_number: str, results: Iterable[dict[str, Any]]) -> None:\n results_list = list(results)\n print(f\"PR #{pr_number}: {len(results_list)} failing checks analyzed.\")\n for result in results_list:\n print(\"-\" * 60)\n print(f\"Check: {result.get('name', '')}\")\n if result.get(\"detailsUrl\"):\n print(f\"Details: {result['detailsUrl']}\")\n run_id = result.get(\"runId\")\n if run_id:\n print(f\"Run ID: {run_id}\")\n job_id = result.get(\"jobId\")\n if job_id:\n print(f\"Job ID: {job_id}\")\n status = result.get(\"status\", \"unknown\")\n print(f\"Status: {status}\")\n\n run_meta = result.get(\"run\", {})\n if run_meta:\n branch = run_meta.get(\"headBranch\", \"\")\n sha = (run_meta.get(\"headSha\") or \"\")[:12]\n workflow = run_meta.get(\"workflowName\") or run_meta.get(\"name\") or \"\"\n conclusion = run_meta.get(\"conclusion\") or run_meta.get(\"status\") or \"\"\n print(f\"Workflow: {workflow} ({conclusion})\")\n if branch or sha:\n print(f\"Branch/SHA: {branch} {sha}\")\n if run_meta.get(\"url\"):\n print(f\"Run URL: {run_meta['url']}\")\n\n if result.get(\"note\"):\n print(f\"Note: {result['note']}\")\n\n if result.get(\"error\"):\n print(f\"Error fetching logs: {result['error']}\")\n continue\n\n snippet = result.get(\"logSnippet\") or \"\"\n if snippet:\n print(\"Failure snippet:\")\n print(indent_block(snippet, prefix=\" \"))\n else:\n print(\"No snippet available.\")\n print(\"-\" * 60)\n\n\ndef indent_block(text: str, prefix: str = \" \") -> str:\n return \"\\n\".join(f\"{prefix}{line}\" for line in text.splitlines())\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "skills/.curated/imagegen/LICENSE.txt", "content": "Apache License\nVersion 2.0, January 2004\nhttp://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf of\n any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nAPPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don\\'t include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\nCopyright [yyyy] [name of copyright owner]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "skills/.curated/imagegen/SKILL.md", "content": "---\nname: \"imagegen\"\ndescription: \"Use when the user asks to generate or edit images via the OpenAI Image API (for example: generate image, edit/inpaint/mask, background removal or replacement, transparent background, product shots, concept art, covers, or batch variants); run the bundled CLI (`scripts/image_gen.py`) and require `OPENAI_API_KEY` for live calls.\"\n---\n\n\n# Image Generation Skill\n\nGenerates or edits images for the current project (e.g., website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, infographics). Defaults to `gpt-image-1.5` and the OpenAI Image API, and prefers the bundled CLI for deterministic, reproducible runs.\n\n## When to use\n- Generate a new image (concept art, product shot, cover, website hero)\n- Edit an existing image (inpainting, masked edits, lighting or weather transformations, background replacement, object removal, compositing, transparent background)\n- Batch runs (many prompts, or many variants across prompts)\n\n## Decision tree (generate vs edit vs batch)\n- If the user provides an input image (or says “edit/retouch/inpaint/mask/translate/localize/change only X”) → **edit**\n- Else if the user needs many different prompts/assets → **generate-batch**\n- Else → **generate**\n\n## Workflow\n1. Decide intent: generate vs edit vs batch (see decision tree above).\n2. Collect inputs up front: prompt(s), exact text (verbatim), constraints/avoid list, and any input image(s)/mask(s). For multi-image edits, label each input by index and role; for edits, list invariants explicitly.\n3. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.\n4. Augment prompt into a short labeled spec (structure + constraints) without inventing new creative requirements.\n5. Run the bundled CLI (`scripts/image_gen.py`) with sensible defaults (see references/cli.md).\n6. For complex edits/generations, inspect outputs (open/view images) and validate: subject, style, composition, text accuracy, and invariants/avoid items.\n7. Iterate: make a single targeted change (prompt or mask), re-run, re-check.\n8. Save/return final outputs and note the final prompt + flags used.\n\n## Temp and output conventions\n- Use `tmp/imagegen/` for intermediate files (for example JSONL batches); delete when done.\n- Write final artifacts under `output/imagegen/` when working in this repo.\n- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.\n\n## Dependencies (install if missing)\nPrefer `uv` for dependency management.\n\nPython packages:\n```\nuv pip install openai pillow\n```\nIf `uv` is unavailable:\n```\npython3 -m pip install openai pillow\n```\n\n## Environment\n- `OPENAI_API_KEY` must be set for live API calls.\n\nIf the key is missing, give the user these steps:\n1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys\n2. Set `OPENAI_API_KEY` as an environment variable in their system.\n3. Offer to guide them through setting the environment variable for their OS/shell if needed.\n- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.\n\nIf installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.\n\n## Defaults & rules\n- Use `gpt-image-1.5` unless the user explicitly asks for `gpt-image-1-mini` or explicitly prefers a cheaper/faster model.\n- Assume the user wants a new image unless they explicitly ask for an edit.\n- Require `OPENAI_API_KEY` before any live API call.\n- Use the OpenAI Python SDK (`openai` package) for all API calls; do not use raw HTTP.\n- If the user requests edits, use `client.images.edit(...)` and include input images (and mask if provided).\n- Prefer the bundled CLI (`scripts/image_gen.py`) over writing new one-off scripts.\n- Never modify `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.\n- If the result isn’t clearly relevant or doesn’t satisfy constraints, iterate with small targeted prompt changes; only ask a question if a missing detail blocks success.\n\n## Prompt augmentation\nReformat user prompts into a structured, production-oriented spec. Only make implicit details explicit; do not invent new requirements.\n\n## Use-case taxonomy (exact slugs)\nClassify each request into one of these buckets and keep the slug consistent across prompts and references.\n\nGenerate:\n- photorealistic-natural — candid/editorial lifestyle scenes with real texture and natural lighting.\n- product-mockup — product/packaging shots, catalog imagery, merch concepts.\n- ui-mockup — app/web interface mockups that look shippable.\n- infographic-diagram — diagrams/infographics with structured layout and text.\n- logo-brand — logo/mark exploration, vector-friendly.\n- illustration-story — comics, children’s book art, narrative scenes.\n- stylized-concept — style-driven concept art, 3D/stylized renders.\n- historical-scene — period-accurate/world-knowledge scenes.\n\nEdit:\n- text-localization — translate/replace in-image text, preserve layout.\n- identity-preserve — try-on, person-in-scene; lock face/body/pose.\n- precise-object-edit — remove/replace a specific element (incl. interior swaps).\n- lighting-weather — time-of-day/season/atmosphere changes only.\n- background-extraction — transparent background / clean cutout.\n- style-transfer — apply reference style while changing subject/scene.\n- compositing — multi-image insert/merge with matched lighting/perspective.\n- sketch-to-render — drawing/line art to photoreal render.\n\nQuick clarification (augmentation vs invention):\n- If the user says “a hero image for a landing page”, you may add *layout/composition constraints* that are implied by that use (e.g., “generous negative space on the right for headline text”).\n- Do not introduce new creative elements the user didn’t ask for (e.g., adding a mascot, changing the subject, inventing brand names/logos).\n\nTemplate (include only relevant lines):\n```\nUse case: \nAsset type: \nPrimary request: \nScene/background: \nSubject:
\nStyle/medium: \nComposition/framing: \nLighting/mood: \nColor palette: \nMaterials/textures: \nQuality: \nInput fidelity (edits): \nText (verbatim): \"\"\nConstraints: \nAvoid: \n```\n\nAugmentation rules:\n- Keep it short; add only details the user already implied or provided elsewhere.\n- Always classify the request into a taxonomy slug above and tailor constraints/composition/quality to that bucket. Use the slug to find the matching example in `references/sample-prompts.md`.\n- If the user gives a broad request (e.g., \"Generate images for this website\"), use judgment to propose tasteful, context-appropriate assets and map each to a taxonomy slug.\n- For edits, explicitly list invariants (\"change only X; keep Y unchanged\").\n- If any critical detail is missing and blocks success, ask a question; otherwise proceed.\n\n## Examples\n\n### Generation example (hero image)\n```\nUse case: stylized-concept\nAsset type: landing page hero\nPrimary request: a minimal hero image of a ceramic coffee mug\nStyle/medium: clean product photography\nComposition/framing: centered product, generous negative space on the right\nLighting/mood: soft studio lighting\nConstraints: no logos, no text, no watermark\n```\n\n### Edit example (invariants)\n```\nUse case: precise-object-edit\nAsset type: product photo background replacement\nPrimary request: replace the background with a warm sunset gradient\nConstraints: change only the background; keep the product and its edges unchanged; no text; no watermark\n```\n\n## Prompting best practices (short list)\n- Structure prompt as scene -> subject -> details -> constraints.\n- Include intended use (ad, UI mock, infographic) to set the mode and polish level.\n- Use camera/composition language for photorealism.\n- Quote exact text and specify typography + placement.\n- For tricky words, spell them letter-by-letter and require verbatim rendering.\n- For multi-image inputs, reference images by index and describe how to combine them.\n- For edits, repeat invariants every iteration to reduce drift.\n- Iterate with single-change follow-ups.\n- For latency-sensitive runs, start with quality=low; use quality=high for text-heavy or detail-critical outputs.\n- For strict edits (identity/layout lock), consider input_fidelity=high.\n- If results feel “tacky”, add a brief “Avoid:” line (stock-photo vibe; cheesy lens flare; oversaturated neon; harsh bloom; oversharpening; clutter) and specify restraint (“editorial”, “premium”, “subtle”).\n\nMore principles: `references/prompting.md`. Copy/paste specs: `references/sample-prompts.md`.\n\n## Guidance by asset type\nAsset-type templates (website assets, game assets, wireframes, logo) are consolidated in `references/sample-prompts.md`.\n\n## CLI + environment notes\n- CLI commands + examples: `references/cli.md`\n- API parameter quick reference: `references/image-api.md`\n- If network approvals / sandbox settings are getting in the way: `references/codex-network.md`\n\n## Reference map\n- **`references/cli.md`**: how to *run* image generation/edits/batches via `scripts/image_gen.py` (commands, flags, recipes).\n- **`references/image-api.md`**: what knobs exist at the API level (parameters, sizes, quality, background, edit-only fields).\n- **`references/prompting.md`**: prompting principles (structure, constraints/invariants, iteration patterns).\n- **`references/sample-prompts.md`**: copy/paste prompt recipes (generate + edit workflows; examples only).\n- **`references/codex-network.md`**: environment/sandbox/network-approval troubleshooting.\n" }, { "path": "skills/.curated/imagegen/agents/openai.yaml", "content": "interface:\n display_name: \"Image Gen\"\n short_description: \"Generate and edit images using OpenAI\"\n icon_small: \"./assets/imagegen-small.svg\"\n icon_large: \"./assets/imagegen.png\"\n default_prompt: \"Generate or edit images for this task and return the final prompt plus selected outputs.\"\n" }, { "path": "skills/.curated/imagegen/references/cli.md", "content": "# CLI reference (`scripts/image_gen.py`)\n\nThis file contains the “command catalog” for the bundled image generation CLI. Keep `SKILL.md` as overview-first; put verbose CLI details here.\n\n## What this CLI does\n- `generate`: generate new images from a prompt\n- `edit`: edit an existing image (optionally with a mask) — inpainting / background replacement / “change only X”\n- `generate-batch`: run many jobs from a JSONL file (one job per line)\n\nReal API calls require **network access** + `OPENAI_API_KEY`. `--dry-run` does not.\n\n## Quick start (works from any repo)\nSet a stable path to the skill CLI (default `CODEX_HOME` is `~/.codex`):\n\n```\nexport CODEX_HOME=\"${CODEX_HOME:-$HOME/.codex}\"\nexport IMAGE_GEN=\"$CODEX_HOME/skills/imagegen/scripts/image_gen.py\"\n```\n\nDry-run (no API call; no network required; does not require the `openai` package):\n\n```\npython \"$IMAGE_GEN\" generate --prompt \"Test\" --dry-run\n```\n\nGenerate (requires `OPENAI_API_KEY` + network):\n\n```\nuv run --with openai python \"$IMAGE_GEN\" generate --prompt \"A cozy alpine cabin at dawn\" --size 1024x1024\n```\n\nNo `uv` installed? Use your active Python env:\n\n```\npython \"$IMAGE_GEN\" generate --prompt \"A cozy alpine cabin at dawn\" --size 1024x1024\n```\n\n## Guardrails (important)\n- Use `python \"$IMAGE_GEN\" ...` (or equivalent full path) for generations/edits/batch work.\n- Do **not** create one-off runners (e.g. `gen_images.py`) unless the user explicitly asks for a custom wrapper.\n- **Never modify** `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.\n\n## Defaults (unless overridden by flags)\n- Model: `gpt-image-1.5`\n- Size: `1024x1024`\n- Quality: `auto`\n- Output format: `png`\n- Background: unspecified (API default). If you set `--background transparent`, also set `--output-format png` or `webp`.\n\n## Quality + input fidelity\n- `--quality` works for `generate`, `edit`, and `generate-batch`: `low|medium|high|auto`.\n- `--input-fidelity` is **edit-only**: `low|high` (use `high` for strict edits like identity or layout lock).\n\nExample:\n```\npython \"$IMAGE_GEN\" edit --image input.png --prompt \"Change only the background\" --quality high --input-fidelity high\n```\n\n## Masks (edits)\n- Use a **PNG** mask; an alpha channel is strongly recommended.\n- The mask should match the input image dimensions.\n- In the edit prompt, repeat invariants (e.g., “change only the background; keep the subject unchanged”) to reduce drift.\n\n## Optional deps\nPrefer `uv run --with ...` for an out-of-the-box run without changing the current project env; otherwise install into your active env:\n\n```\nuv pip install openai\n```\n\n## Common recipes\n\nGenerate + also write a downscaled copy for fast web loading:\n\n```\nuv run --with openai --with pillow python \"$IMAGE_GEN\" generate \\\n --prompt \"A cozy alpine cabin at dawn\" \\\n --size 1024x1024 \\\n --downscale-max-dim 1024\n```\n\nNotes:\n- Downscaling writes an extra file next to the original (default suffix `-web`, e.g. `output-web.png`).\n- Downscaling requires Pillow (use `uv run --with pillow ...` or install it into your env).\n\nGenerate with augmentation fields:\n\n```\npython \"$IMAGE_GEN\" generate \\\n --prompt \"A minimal hero image of a ceramic coffee mug\" \\\n --use-case \"landing page hero\" \\\n --style \"clean product photography\" \\\n --composition \"centered product, generous negative space\" \\\n --constraints \"no logos, no text\"\n```\n\nGenerate multiple prompts concurrently (async batch):\n\n```\nmkdir -p tmp/imagegen\ncat > tmp/imagegen/prompts.jsonl << 'EOF'\n{\"prompt\":\"Cavernous hangar interior with a compact shuttle parked center-left, open bay door\",\"use_case\":\"game concept art environment\",\"composition\":\"wide-angle, low-angle, cinematic framing\",\"lighting\":\"volumetric light rays through drifting fog\",\"constraints\":\"no logos or trademarks; no watermark\",\"size\":\"1536x1024\"}\n{\"prompt\":\"Gray wolf in profile in a snowy forest, crisp fur texture\",\"use_case\":\"wildlife photography print\",\"composition\":\"100mm, eye-level, shallow depth of field\",\"constraints\":\"no logos or trademarks; no watermark\",\"size\":\"1024x1024\"}\nEOF\n\npython \"$IMAGE_GEN\" generate-batch --input tmp/imagegen/prompts.jsonl --out-dir out --concurrency 5\n\n# Cleanup (recommended)\nrm -f tmp/imagegen/prompts.jsonl\n```\n\nNotes:\n- Use `--concurrency` to control parallelism (default `5`). Higher concurrency can hit rate limits; the CLI retries on transient errors.\n- Per-job overrides are supported in JSONL (e.g., `size`, `quality`, `background`, `output_format`, `n`, and prompt-augmentation fields).\n- `--n` generates multiple variants for a single prompt; `generate-batch` is for many different prompts.\n- Treat the JSONL file as temporary: write it under `tmp/` and delete it after the run (don’t commit it).\n\nEdit:\n\n```\npython \"$IMAGE_GEN\" edit --image input.png --mask mask.png --prompt \"Replace the background with a warm sunset\"\n```\n\n## CLI notes\n- Supported sizes: `1024x1024`, `1536x1024`, `1024x1536`, or `auto`.\n- Transparent backgrounds require `output_format` to be `png` or `webp`.\n- Default output is `output.png`; multiple images become `output-1.png`, `output-2.png`, etc.\n- Use `--no-augment` to skip prompt augmentation.\n\n## See also\n- API parameter quick reference: `references/image-api.md`\n- Prompt examples: `references/sample-prompts.md`\n" }, { "path": "skills/.curated/imagegen/references/codex-network.md", "content": "# Codex network approvals / sandbox notes\n\nThis guidance is intentionally isolated from `SKILL.md` because it can vary by environment and may become stale. Prefer the defaults in your environment when in doubt.\n\n## Why am I asked to approve every image generation call?\nImage generation uses the OpenAI Image API, so the CLI needs outbound network access. In many Codex setups, network access is disabled by default (especially under stricter sandbox modes), and/or the approval policy may require confirmation before networked commands run.\n\n## How do I reduce repeated approval prompts (network)?\nIf you trust the repo and want fewer prompts, enable network access for the relevant sandbox mode and relax the approval policy.\n\nExample `~/.codex/config.toml` pattern:\n\n```\napproval_policy = \"never\"\nsandbox_mode = \"workspace-write\"\n\n[sandbox_workspace_write]\nnetwork_access = true\n```\n\nOr for a single session:\n\n```\ncodex --sandbox workspace-write --ask-for-approval never\n```\n\n## Safety note\nUse caution: enabling network and disabling approvals reduces friction but increases risk if you run untrusted code or work in an untrusted repository.\n" }, { "path": "skills/.curated/imagegen/references/image-api.md", "content": "# Image API quick reference\n\n## Endpoints\n- Generate: `POST /v1/images/generations` (`client.images.generate(...)`)\n- Edit: `POST /v1/images/edits` (`client.images.edit(...)`)\n\n## Models\n- Default: `gpt-image-1.5`\n- Alternatives: `gpt-image-1-mini` (for faster, lower-cost generation)\n\n## Core parameters (generate + edit)\n- `prompt`: text prompt\n- `model`: image model\n- `n`: number of images (1-10)\n- `size`: `1024x1024`, `1536x1024`, `1024x1536`, or `auto`\n- `quality`: `low`, `medium`, `high`, or `auto`\n- `background`: `transparent`, `opaque`, or `auto` (transparent requires `png`/`webp`)\n- `output_format`: `png` (default), `jpeg`, `webp`\n- `output_compression`: 0-100 (jpeg/webp only)\n- `moderation`: `auto` (default) or `low`\n\n## Edit-specific parameters\n- `image`: one or more input images (first image is primary)\n- `mask`: optional mask image (same size, alpha channel required)\n- `input_fidelity`: `low` (default) or `high` (support varies by model) - set it to `high` if the user needs a very specific edit and you can't achieve it with the default `low` fidelity.\n\n## Output\n- `data[]` list with `b64_json` per image\n\n## Limits & notes\n- Input images and masks must be under 50MB.\n- Use edits endpoint when the user requests changes to an existing image.\n- Masking is prompt-guided; exact shapes are not guaranteed.\n- Large sizes and high quality increase latency and cost.\n- For fast iteration or latency-sensitive runs, start with `quality=low`; raise to `high` for text-heavy or detail-critical outputs.\n- Use `input_fidelity=high` for strict edits (identity preservation, layout lock, or precise compositing).\n" }, { "path": "skills/.curated/imagegen/references/prompting.md", "content": "# Prompting best practices (gpt-image-1.5)\n\n## Contents\n- [Structure](#structure)\n- [Specificity](#specificity)\n- [Avoiding “tacky” outputs](#avoiding-tacky-outputs)\n- [Composition & layout](#composition--layout)\n- [Constraints & invariants](#constraints--invariants)\n- [Text in images](#text-in-images)\n- [Multi-image inputs](#multi-image-inputs)\n- [Iterate deliberately](#iterate-deliberately)\n- [Quality vs latency](#quality-vs-latency)\n- [Use-case tips](#use-case-tips)\n- [Where to find copy/paste recipes](#where-to-find-copypaste-recipes)\n\n## Structure\n- Use a consistent order: scene/background -> subject -> key details -> constraints -> output intent.\n- Include intended use (ad, UI mock, infographic) to set the mode and polish level.\n- For complex requests, use short labeled lines instead of a long paragraph.\n\n## Specificity\n- Name materials, textures, and visual medium (photo, watercolor, 3D render).\n- For photorealism, include camera/composition language (lens, framing, lighting).\n- Add targeted quality cues only when needed (film grain, textured brushstrokes, macro detail); avoid generic \"8K\" style prompts.\n\n## Avoiding “tacky” outputs\n- Don’t use vibe-only buzzwords (“epic”, “cinematic”, “trending”, “8k”, “award-winning”, “unreal engine”, “artstation”) unless the user explicitly wants that look.\n- Specify restraint: “minimal”, “editorial”, “premium”, “subtle”, “natural color grading”, “soft contrast”, “no harsh bloom”, “no oversharpening”.\n- For 3D/illustration, name the finish you want: “matte”, “paper grain”, “ink texture”, “flat color with soft shadow”; avoid “glossy plastic” unless requested.\n- Add a short negative line when needed (especially for marketing art): “Avoid: stock-photo vibe; cheesy lens flare; oversaturated neon; excessive bokeh; fake-looking smiles; clutter”.\n\n## Composition & layout\n- Specify framing and viewpoint (close-up, wide, top-down) and placement (\"logo top-right\").\n- Call out negative space if you need room for UI or overlays.\n\n## Constraints & invariants\n- State what must not change (\"keep background unchanged\").\n- For edits, say \"change only X; keep Y unchanged\" and repeat invariants on every iteration to reduce drift.\n\n## Text in images\n- Put literal text in quotes or ALL CAPS and specify typography (font style, size, color, placement).\n- Spell uncommon words letter-by-letter if accuracy matters.\n- For in-image copy, require verbatim rendering and no extra characters.\n\n## Multi-image inputs\n- Reference inputs by index and role (\"Image 1: product, Image 2: style\").\n- Describe how to combine them (\"apply Image 2's style to Image 1\").\n- For compositing, specify what moves where and what must remain unchanged.\n\n## Iterate deliberately\n- Start with a clean base prompt, then make small single-change edits.\n- Re-specify critical constraints when you iterate.\n\n## Quality vs latency\n- For latency-sensitive runs, start at `quality=low` and only raise it if needed.\n- Use `quality=high` for text-heavy or detail-critical images.\n- For strict edits (identity preservation, layout lock), consider `input_fidelity=high`.\n\n## Use-case tips\nGenerate:\n- photorealistic-natural: Prompt as if a real photo is captured in the moment; use photography language (lens, lighting, framing); call for real texture (pores, wrinkles, fabric wear, imperfections); avoid studio polish or staging; use `quality=high` when detail matters.\n- product-mockup: Describe the product/packaging and materials; ensure clean silhouette and label clarity; if in-image text is needed, require verbatim rendering and specify typography.\n- ui-mockup: Describe a real product; focus on layout, hierarchy, and common UI elements; avoid concept-art language so it looks shippable.\n- infographic-diagram: Define the audience and layout flow; label parts explicitly; require verbatim text; use `quality=high`.\n- logo-brand: Keep it simple and scalable; ask for a strong silhouette and balanced negative space; avoid gradients and fine detail.\n- illustration-story: Define panels or scene beats; keep each action concrete; for continuity, restate character traits and outfit each time.\n- stylized-concept: Specify style cues, material finish, and rendering approach (3D, painterly, clay); add a short \"Avoid\" line to prevent tacky effects.\n- historical-scene: State the location/date and required period accuracy; constrain clothing, props, and environment to match the era.\n\nEdit:\n- text-localization: Change only the text; preserve layout, typography, spacing, and hierarchy; no extra words or reflow unless needed.\n- identity-preserve: Lock identity (face, body, pose, hair, expression); change only the specified elements; match lighting and shadows; use `input_fidelity=high` if likeness drifts.\n- precise-object-edit: Specify exactly what to remove/replace; preserve surrounding texture and lighting; keep everything else unchanged.\n- lighting-weather: Change only environmental conditions (light, shadows, atmosphere, precipitation); keep geometry, framing, and subject identity.\n- background-extraction: Request transparent background; crisp silhouette; no halos; preserve label text exactly; optionally add a subtle contact shadow.\n- style-transfer: Specify style cues to preserve (palette, texture, brushwork) and what must change; add \"no extra elements\" to prevent drift.\n- compositing: Reference inputs by index; specify what moves where; match lighting, perspective, and scale; keep background and framing unchanged.\n- sketch-to-render: Preserve layout, proportions, and perspective; add plausible materials, lighting, and environment; \"do not add new elements or text.\"\n\n## Where to find copy/paste recipes\nFor copy/paste prompt specs (examples only), see `references/sample-prompts.md`. This file focuses on principles, structure, and iteration patterns.\n" }, { "path": "skills/.curated/imagegen/references/sample-prompts.md", "content": "# Sample prompts (copy/paste)\n\nUse these as starting points (recipes only). Keep user-provided requirements; do not invent new creative elements.\n\nFor prompting principles (structure, invariants, iteration), see `references/prompting.md`.\n\n## Generate\n\n### photorealistic-natural\n```\nUse case: photorealistic-natural\nPrimary request: candid photo of an elderly sailor on a small fishing boat adjusting a net\nScene/background: coastal water with soft haze\nSubject: weathered skin with wrinkles and sun texture; a calm dog on deck nearby\nStyle/medium: photorealistic candid photo\nComposition/framing: medium close-up, eye-level, 50mm lens\nLighting/mood: soft coastal daylight, shallow depth of field, subtle film grain\nMaterials/textures: real skin texture, worn fabric, salt-worn wood\nConstraints: natural color balance; no heavy retouching; no glamorization; no watermark\nAvoid: studio polish; staged look\nQuality: high\n```\n\n### product-mockup\n```\nUse case: product-mockup\nPrimary request: premium product photo of a matte black shampoo bottle with a minimal label\nScene/background: clean studio gradient from light gray to white\nSubject: single bottle centered with subtle reflection\nStyle/medium: premium product photography\nComposition/framing: centered, slight three-quarter angle, generous padding\nLighting/mood: softbox lighting, clean highlights, controlled shadows\nMaterials/textures: matte plastic, crisp label printing\nConstraints: no logos or trademarks; no watermark\nQuality: high\n```\n\n### ui-mockup\n```\nUse case: ui-mockup\nPrimary request: mobile app UI for a local farmers market with vendors and specials\nScene/background: clean white background with subtle natural accents\nSubject: header, vendor list with small photos, \"Today's specials\" section, location and hours\nStyle/medium: realistic product UI, not concept art\nComposition/framing: iPhone frame, balanced spacing and hierarchy\nConstraints: practical layout, clear typography, no logos or trademarks, no watermark\n```\n\n### infographic-diagram\n```\nUse case: infographic-diagram\nPrimary request: detailed infographic of an automatic coffee machine flow\nScene/background: clean, light neutral background\nSubject: bean hopper -> grinder -> brew group -> boiler -> water tank -> drip tray\nStyle/medium: clean vector-like infographic with clear callouts and arrows\nComposition/framing: vertical poster layout, top-to-bottom flow\nText (verbatim): \"Bean Hopper\", \"Grinder\", \"Brew Group\", \"Boiler\", \"Water Tank\", \"Drip Tray\"\nConstraints: clear labels, strong contrast, no logos or trademarks, no watermark\nQuality: high\n```\n\n### logo-brand\n```\nUse case: logo-brand\nPrimary request: original logo for \"Field & Flour\", a local bakery\nStyle/medium: vector logo mark; flat colors; minimal\nComposition/framing: single centered logo on plain background with padding\nConstraints: strong silhouette, balanced negative space; original design only; no gradients unless essential; no trademarks; no watermark\n```\n\n### illustration-story\n```\nUse case: illustration-story\nPrimary request: 4-panel comic about a pet left alone at home\nScene/background: cozy living room across panels\nSubject: pet reacting to the owner leaving, then relaxing, then returning to a composed pose\nStyle/medium: comic illustration with clear panels\nComposition/framing: 4 equal-sized vertical panels, readable actions per panel\nConstraints: no text; no logos or trademarks; no watermark\n```\n\n### stylized-concept\n```\nUse case: stylized-concept\nPrimary request: cavernous hangar interior with tall support beams and drifting fog\nScene/background: industrial hangar interior, deep scale, light haze\nSubject: compact shuttle, parked center-left, bay door open\nStyle/medium: cinematic concept art, industrial realism\nComposition/framing: wide-angle, low-angle, cinematic framing\nLighting/mood: volumetric light rays cutting through fog\nConstraints: no logos or trademarks; no watermark\n```\n\n### historical-scene\n```\nUse case: historical-scene\nPrimary request: outdoor crowd scene in Bethel, New York on August 16, 1969\nScene/background: open field, temporary stages, period-accurate tents and signage\nSubject: crowd in period-accurate clothing, authentic staging and environment\nStyle/medium: photorealistic photo\nComposition/framing: wide shot, eye-level\nConstraints: period-accurate details; no modern objects; no logos or trademarks; no watermark\n```\n\n## Asset type templates (taxonomy-aligned)\n\n### Website assets template\n```\nUse case: \nAsset type: \nPrimary request: \nScene/background: \nSubject:
\nStyle/medium: \nComposition/framing: \nLighting/mood: \nColor palette: \nConstraints: \n```\n\n### Website assets example: minimal hero background\n```\nUse case: stylized-concept\nAsset type: landing page hero background\nPrimary request: minimal abstract background with a soft gradient and subtle texture (calm, modern)\nStyle/medium: matte illustration / soft-rendered abstract background (not glossy 3D)\nComposition/framing: wide composition; large negative space on the right for headline\nLighting/mood: gentle studio glow\nColor palette: cool neutrals with a restrained blue accent\nConstraints: no text; no logos; no watermark\n```\n\n### Website assets example: feature section illustration\n```\nUse case: stylized-concept\nAsset type: feature section illustration\nPrimary request: simple abstract shapes suggesting connection and flow (tasteful, minimal)\nScene/background: subtle light-gray backdrop with faint texture\nStyle/medium: flat illustration; soft shadows; restrained contrast\nComposition/framing: centered cluster; open margins for UI\nColor palette: muted teal and slate, low contrast accents\nConstraints: no text; no logos; no watermark\n```\n\n### Website assets example: blog header image\n```\nUse case: photorealistic-natural\nAsset type: blog header image\nPrimary request: overhead desk scene with notebook, pen, and coffee cup\nScene/background: warm wooden tabletop\nStyle/medium: photorealistic photo\nComposition/framing: wide crop; subject placed left; right side left empty\nLighting/mood: soft morning light\nConstraints: no text; no logos; no watermark\n```\n\n### Game assets template\n```\nUse case: stylized-concept\nAsset type: \nPrimary request: \nScene/background: (if applicable)\nSubject:
\nStyle/medium: ; \nComposition/framing: ; ; \nLighting/mood: