opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/api-shield/gotchas.md

@@ -0,0 +1,51 @@
+# Gotchas & Troubleshooting
+
+## Schema Blocking Valid Reqs
+
+Firewall Events show violations? 1) Check details 2) Review schema (Settings) 3) Test Swagger Editor 4) Log mode 5) Update schema
+
+Validated: date-time,time,date,email,hostname,ipv4/6,uri(-reference),iri(-reference),int32/64,float,double,password,uuid,byte,uint64
+
+oneOf: Zero matches (missing discriminator), Multiple (ambiguous)
+
+## JWT Failing
+
+1) JWKS match IdP? 2) `exp` valid? 3) Header/cookie name? 4) Test jwt.io 5) Clock skew?
+
+## Discovery Missing
+
+Needs 500+ reqs/10d, 2xx from edge, not Workers direct. Check threshold, codes, session ID config. ML updates daily. Path norm: `/profile/238` → `/profile/{var1}`
+
+## Sequence False Positives
+
+Lookback: 10 reqs to managed endpoints, 10min (contact for adjust). Check session ID uniqueness, neg vs pos model
+
+## Perf
+
+Schema: ~1-2ms, JWT: ~0.5-1ms, mTLS: ~2-5ms, Sequence: ~0.5ms
+
+## Best Practices
+
+1. Discovery first (map before enforce)
+2. Progressive: Log → Block critical → Full
+3. Session IDs unique per user
+4. Validate schema (Swagger Editor)
+5. Automate JWKS rotation (Worker cron)
+6. Fallthrough rules (zombie APIs)
+7. Logpush + alerts
+8. Rate limit w/JWT claims
+9. Layer Bot Management
+10. Test staging
+
+## Limits
+
+Schema: OpenAPI v3.0.x only, no ext refs/non-basic paths, 10K ops, need `type`+`schema`, default `style`/`explode`, no `content` in params, no obj param validation, no `anyOf` in params
+JWT: Headers/cookies only, validates managed endpoints only
+Sequence (Beta): Needs endpoints+session ID, contact team
+
+## Errors
+
+"Token invalid": Config wrong, JWKS mismatch, expired
+"Schema violation": Missing fields, wrong types, spec mismatch
+"Fallthrough": Unknown endpoint, pattern mismatch
+"mTLS failed": Cert untrusted/expired, wrong CA

package/dist/template/.opencode/skill/cloudflare/references/api-shield/patterns.md

@@ -0,0 +1,145 @@
+# Patterns & Use Cases
+
+## Protect API with Schema + JWT
+
+```bash
+# 1. Upload OpenAPI schema
+POST /zones/{zone_id}/api_gateway/user_schemas
+
+# 2. Configure JWT validation
+POST /zones/{zone_id}/api_gateway/token_validation
+{
+  "name": "Auth0",
+  "location": {"header": "Authorization"},
+  "jwks": "{...}"
+}
+
+# 3. Create JWT rule
+POST /zones/{zone_id}/api_gateway/jwt_validation_rules
+
+# 4. Set schema validation action
+PUT /zones/{zone_id}/api_gateway/settings/schema_validation
+{"validation_default_mitigation_action": "block"}
+```
+
+## Progressive Rollout
+
+```
+1. Log mode: Observe false positives
+   - Schema: Action = Log
+   - JWT: Action = Log
+
+2. Block subset: Protect critical endpoints
+   - Change specific endpoint actions to Block
+   - Monitor firewall events
+
+3. Full enforcement: Block all violations
+   - Change default action to Block
+   - Handle fallthrough with custom rule
+```
+
+## Fallthrough Detection (Zombie APIs)
+
+```javascript
+// WAF Custom Rule
+(cf.api_gateway.fallthrough_triggered and http.host eq "api.example.com")
+// Action: Log (discover unknown) or Block (strict)
+```
+
+## Rate Limiting by User
+
+```javascript
+// Rate Limiting Rule
+(http.host eq "api.example.com" and
+ lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub") ne "")
+
+// Rate: 100 req/60s
+// Counting: lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
+```
+
+## Architecture Patterns
+
+### Public API (High Security)
+```
+Cloudflare Edge
+├── API Discovery (identify endpoints)
+├── Schema Validation (enforce OpenAPI)
+├── JWT Validation (verify tokens)
+├── Rate Limiting (per-user)
+├── Bot Management (filter abuse)
+└── Origin → API server
+```
+
+### Partner API (mTLS + Schema)
+```
+Cloudflare Edge
+├── mTLS (verify client certs)
+├── Schema Validation (validate payloads)
+├── Sequence Mitigation (enforce order)
+└── Origin → API server
+```
+
+### Internal API (Discovery + Monitoring)
+```
+Cloudflare Edge
+├── API Discovery (map shadow APIs)
+├── Schema Learning (auto-generate specs)
+├── Authentication Posture (audit coverage)
+└── Origin → API server
+```
+
+## OWASP API Security Top 10 Mapping
+
+| OWASP Issue | API Shield Solutions |
+|-------------|---------------------|
+| Broken Object Level Authorization | BOLA detection, Sequence mitigation, Schema, JWT, Rate Limiting |
+| Broken Authentication | Auth Posture, mTLS, JWT, Credential Checks, Bot Management |
+| Broken Object Property Auth | Schema validation, JWT validation |
+| Unrestricted Resource | Rate Limiting, Sequence, Bot Management, GraphQL protection |
+| Broken Function Level Auth | Schema validation, JWT validation |
+| Unrestricted Business Flows | Sequence mitigation, Bot Management, GraphQL |
+| SSRF | Schema, WAF managed rules, WAF custom |
+| Security Misconfiguration | Sequence, Schema, WAF managed, GraphQL |
+| Improper Inventory | Discovery, Schema learning |
+| Unsafe API Consumption | JWT validation, WAF managed |
+
+## Monitoring
+
+**Security Events:**
+```
+Security > Events
+Filter: Action = block, Service = API Shield
+```
+
+**Firewall Analytics:**
+```
+Analytics > Security
+Filter by cf.api_gateway.* fields
+```
+
+**Logpush fields:**
+```json
+{
+  "APIGatewayAuthIDPresent": true,
+  "APIGatewayRequestViolatesSchema": false,
+  "APIGatewayFallthroughDetected": false,
+  "JWTValidationResult": "valid",
+  "ClientCertFingerprint": "abc123..."
+}
+```
+
+## Availability
+
+| Feature | Availability |
+|---------|-------------|
+| mTLS (CF-managed CA) | All plans |
+| Endpoint Management | All plans (limited ops) |
+| Schema Validation | All plans (limited ops) |
+| API Discovery | Enterprise only |
+| JWT Validation | Enterprise (add-on) |
+| Sequence Mitigation | Enterprise (closed beta) |
+| BOLA Detection | Enterprise (add-on) |
+| Volumetric Abuse | Enterprise (add-on) |
+| Full Suite | Enterprise add-on |
+
+Enterprise: 10K ops (contact for higher), non-contract preview available.

package/dist/template/.opencode/skill/cloudflare/references/argo-smart-routing/README.md

@@ -0,0 +1,16 @@
+# Cloudflare Argo Smart Routing Skill Reference
+
+## Overview
+
+Cloudflare Argo Smart Routing is a performance optimization service that detects real-time network issues and routes web traffic across the most efficient network path. This skill provides comprehensive guidance for implementing, configuring, and managing Argo Smart Routing via API, CLI...
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, deployment, configuration
+- **[api.md](./api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](./patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/)

package/dist/template/.opencode/skill/cloudflare/references/argo-smart-routing/api.md

@@ -0,0 +1,50 @@
+## API Reference
+
+### Base Endpoint
+```
+https://api.cloudflare.com/client/v4
+```
+
+### Authentication
+Use API tokens with Zone:Argo Smart Routing:Edit permissions:
+
+```bash
+# Headers required
+X-Auth-Email: user@example.com
+Authorization: Bearer YOUR_API_TOKEN
+```
+
+### Get Argo Smart Routing Status
+
+**Endpoint:** `GET /zones/{zone_id}/argo/smart_routing`
+
+**Description:** Retrieves current Argo Smart Routing enablement status.
+
+**cURL Example:**
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+**Response:**
+```json
+{
+  "result": {
+    "id": "smart_routing",
+    "value": "on",
+    "editable": true,
+    "modified_on": "2024-01-11T12:00:00Z"
+  },
+  "success": true,
+  "errors": [],
+  "messages": []
+}
+```
+
+**TypeScript SDK Example:**
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKE

package/dist/template/.opencode/skill/cloudflare/references/argo-smart-routing/configuration.md

@@ -0,0 +1,53 @@
+## Configuration Management
+
+### Infrastructure as Code (Terraform)
+
+```hcl
+# terraform/argo.tf
+# Note: Use Cloudflare Terraform provider
+
+resource "cloudflare_argo" "example" {
+  zone_id        = var.zone_id
+  smart_routing  = "on"
+  tiered_caching = "on"
+}
+
+variable "zone_id" {
+  description = "Cloudflare Zone ID"
+  type        = string
+}
+
+output "argo_enabled" {
+  value       = cloudflare_argo.example.smart_routing
+  description = "Argo Smart Routing status"
+}
+```
+
+### Environment-Based Configuration
+
+```typescript
+// config/argo.ts
+interface ArgoEnvironmentConfig {
+  enabled: boolean;
+  tieredCache: boolean;
+  monitoring: {
+    usageAlerts: boolean;
+    threshold: number;
+  };
+}
+
+const configs: Record<string, ArgoEnvironmentConfig> = {
+  production: {
+    enabled: true,
+    tieredCache: true,
+    monitoring: {
+      usageAlerts: true,
+      threshold: 1000, // GB
+    },
+  },
+  staging: {
+    enabled: true,
+    tieredCache: false,
+    monitoring: {
+      usageAlerts: false,
+      th

package/dist/template/.opencode/skill/cloudflare/references/argo-smart-routing/gotchas.md

@@ -0,0 +1,16 @@
+## Best Practices Summary
+
+1. **Always check editability** before attempting to enable/disable Argo
+2. **Set up billing notifications** to avoid unexpected costs
+3. **Combine with Tiered Cache** for maximum performance benefit
+4. **Use in production only** - disable for dev/staging to control costs
+5. **Monitor analytics** - require 500+ requests in 48h for detailed metrics
+6. **Handle errors gracefully** - check for billing, permissions, zone compatibility
+7. **Test configuration changes** in staging before production
+8. **Use TypeScript SDK** for type safety and better developer experience
+9. **Implement retry logic** for API calls in production systems
+10. **Document zone-specific settings** for team visibility
+
+## Additional Resources
+
+- [Official Argo Smart Routing Docs](https://devel

package/dist/template/.opencode/skill/cloudflare/references/argo-smart-routing/patterns.md

@@ -0,0 +1,45 @@
+## Integration with Tiered Cache
+
+Combine Argo Smart Routing with Tiered Cache for maximum performance:
+
+**Endpoint:** `PATCH /zones/{zone_id}/argo/tiered_caching`
+
+**Benefits:**
+- Argo optimizes routing between edge and origin
+- Tiered Cache reduces origin requests via cache hierarchy
+- Combined: optimal network path + reduced origin load
+
+**Enable Both Services:**
+```typescript
+async function enableArgoWithTieredCache(
+  client: Cloudflare,
+  zoneId: string
+) {
+  // Enable Argo Smart Routing
+  await client.argo.smartRouting.edit({
+    zone_id: zoneId,
+    value: 'on',
+  });
+
+  // Enable Tiered Caching
+  await client.argo.tieredCaching.edit({
+    zone_id: zoneId,
+    value: 'on',
+  });
+
+  console.log('Argo Smart Routing and Tiered Cache enabled');
+}
+```
+
+**Architecture Flow:**
+```
+Visitor → Edge Data Center (Lower-Tier)
+         ↓ [Cache Miss]
+         Upper-Tier Data Center
+         ↓ [Cache Miss + Argo Smart Route]
+         Origin Server
+```
+
+## Usage-Based Billing Management
+
+### S

package/dist/template/.opencode/skill/cloudflare/references/bindings/README.md

@@ -0,0 +1,14 @@
+# Cloudflare Bindings Skill Reference
+
+Expert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources....
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, deployment, configuration
+- **[api.md](./api.md)** - API endpoints, methods, interfaces
+- **[patterns.md](./patterns.md)** - Common patterns, use cases, examples
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, best practices, limitations
+
+## See Also
+
+- [Cloudflare Docs](https://developers.cloudflare.com/)

package/dist/template/.opencode/skill/cloudflare/references/bindings/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+See main documentation.

package/dist/template/.opencode/skill/cloudflare/references/bindings/configuration.md

@@ -0,0 +1,58 @@
+## Wrangler Configuration Patterns
+
+### JSON vs TOML
+
+**JSON (Recommended for new projects):**
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-01-01",
+  "vars": {
+    "API_URL": "https://api.example.com"
+  }
+}
+```
+
+**TOML (Legacy):**
+```toml
+# wrangler.toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+API_URL = "https://api.example.com"
+```
+
+### Environment-Specific Configuration
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-01-01",
+  
+  // Production bindings
+  "vars": {
+    "ENV": "production"
+  },
+  "kv_namespaces": [
+    {
+      "binding": "CACHE",
+      "id": "prod-kv-id"
+    }
+  ],
+  
+  // Environment overrides
+  "env": {
+    "staging": {
+      "vars": {
+        "ENV": "staging"
+      },
+      "kv_namespaces": [
+        {
+          "binding": "CACHE",
+          "id": "staging-kv-id

package/dist/template/.opencode/skill/cloudflare/references/bindings/gotchas.md

@@ -0,0 +1,35 @@
+## Troubleshooting
+
+### Binding Not Found
+```
+Error: env.MY_KV is undefined
+```
+**Solutions:**
+1. Check binding name matches config
+2. Run `npx wrangler types` to regenerate types
+3. Verify binding exists in current environment
+4. Check for typos in `wrangler.jsonc`
+
+### Type Errors
+```
+Property 'MY_KV' does not exist on type 'Env'
+```
+**Solution:** Run `npx wrangler types`
+
+### Preview Binding Required
+```
+Error: preview_id is required for --remote
+```
+**Solution:** Add preview_id to config or use local mode
+
+### Stale Binding Values
+```
+Secret updated but Worker still uses old value
+```
+**Solution:** Avoid caching `env` values in global scope
+
+## Security Best Practices
+
+1. **Never commit secrets to config files**
+   - Use `npx wrangler secret put` for sensitive values
+   - Secrets are e

package/dist/template/.opencode/skill/cloudflare/references/bindings/patterns.md

@@ -0,0 +1,37 @@
+## Common Anti-Patterns
+
+### ❌ Hardcoding Credentials
+```typescript
+// DON'T
+const apiKey = 'sk_live_abc123';
+```
+**✅ Use secrets:**
+```bash
+npx wrangler secret put API_KEY
+```
+
+### ❌ Using REST API from Worker
+```typescript
+// DON'T
+await fetch('https://api.cloudflare.com/client/v4/accounts/.../kv/...');
+```
+**✅ Use bindings:**
+```typescript
+await env.MY_KV.get('key');
+```
+
+### ❌ Polling KV/D1 for Changes
+```typescript
+// DON'T
+setInterval(() => {
+  const config = await env.KV.get('config');
+}, 1000);
+```
+**✅ Use Durable Objects for real-time state**
+
+### ❌ Storing Large Data in env.vars
+```typescript
+// DON'T
+{ "vars": { "HUGE_CONFIG": "..." } } // Max 5KB per var
+```
+**✅ Use KV/R2 for large data**

package/dist/template/.opencode/skill/cloudflare/references/bot-management/README.md

@@ -0,0 +1,71 @@
+# Cloudflare Bot Management
+
+Enterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.
+
+## Overview
+
+Bot Management provides multi-tier protection:
+- **Free (Bot Fight Mode)**: Auto-blocks definite bots, no config
+- **Pro/Business (Super Bot Fight Mode)**: Configurable actions, static resource protection, analytics groupings
+- **Enterprise (Bot Management)**: Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics
+
+## Quick Start
+
+```txt
+# Dashboard: Security > Bots
+# Enterprise: Deploy rule template
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block
+(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge
+```
+
+## Core Concepts
+
+**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.
+
+**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).
+
+**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`.
+
+## Platform Limits
+
+| Plan | Bot Scores | JA3/JA4 | Custom Rules | Analytics Retention |
+|------|------------|---------|--------------|---------------------|
+| Free | No (auto-block only) | No | 5 | N/A (no analytics) |
+| Pro/Business | Groupings only | No | 20/100 | 30 days (72h at a time) |
+| Enterprise | 1-99 granular | Yes | 1,000+ | 30 days (1 week at a time) |
+
+## Basic Patterns
+
+```typescript
+// Workers: Check bot score
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const botScore = request.cf?.botManagement?.score;
+    if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {
+      return new Response('Bot detected', { status: 403 });
+    }
+    return fetch(request);
+  }
+};
+```
+
+```txt
+# WAF: Block definite bots
+(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)
+
+# WAF: Protect sensitive endpoints
+(cf.bot_management.score lt 50 and http.request.uri.path in {"/login" "/checkout"} and not cf.bot_management.verified_bot)
+```
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates
+- [api.md](./api.md) - Workers BotManagement interface, WAF fields, JA4 Signals
+- [patterns.md](./patterns.md) - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling
+- [gotchas.md](./gotchas.md) - False positives/negatives, score=0 issues, JSD limitations, CSP requirements
+
+## See Also
+
+- [waf](../waf/) - WAF custom rules for bot enforcement
+- [workers](../workers/) - Workers request.cf.botManagement API
+- [api-shield](../api-shield/) - API-specific bot protection