opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/ai-search/api.md

@@ -0,0 +1,38 @@
+## REST API
+
+**Base URL:** `https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{AUTORAG_NAME}`
+
+**Note:** API endpoints still use `autorag` naming; functionality identical to AI Search
+
+### Authentication
+
+Create API token with permissions:
+- `AI Search - Read`
+- `AI Search Edit`
+
+```bash
+curl -H "Authorization: Bearer {API_TOKEN}" \
+  -H "Content-Type: application/json"
+```
+
+### AI Search Endpoint
+
+```bash
+curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{AUTORAG_NAME}/ai-search \
+-H "Authorization: Bearer {API_TOKEN}" \
+-H "Content-Type: application/json" \
+-d '{
+  "query": "How do I configure caching?",
+  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+  "system_prompt": "You are a technical documentation assistant.",
+  "rewrite_query": true,
+  "max_num_results": 10,
+  "ranking_options": {
+    "score_threshold": 0.3
+  },
+  "reranking": {
+    "enabled": true,
+    "model": "@cf/baai/bge-reranker-base"
+  },
+  "stream": false,
+  "fil

package/dist/template/.opencode/skill/cloudflare/references/ai-search/configuration.md

@@ -0,0 +1,52 @@
+### Configuration
+
+**wrangler.toml:**
+```toml
+[ai]
+binding = "AI"
+```
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "ai": {
+    "binding": "AI"
+  }
+}
+```
+
+### Code Patterns
+
+#### AI Search with Generation
+```typescript
+// Generate AI response with retrieved context
+const answer = await env.AI.autorag("my-autorag").aiSearch({
+  query: "How do I configure rate limits?",
+  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+  rewrite_query: true,
+  max_num_results: 10,
+  ranking_options: {
+    score_threshold: 0.3
+  },
+  reranking: {
+    enabled: true,
+    model: "@cf/baai/bge-reranker-base"
+  },
+  stream: true
+});
+
+// Response includes: search_query, response, data[], has_more, next_page
+```
+
+#### Search Only (No Generation)
+```typescript
+// Retrieve relevant chunks without generation
+const results = await env.AI.autorag("my-autorag").search({
+  query: "rate limiting configuration",
+  rewrite_query: true,
+  max_num_results: 5,
+  ranking_options: {
+    score_threshold: 0.4
+  },
+  reranking: {
+    enab

package/dist/template/.opencode/skill/cloudflare/references/ai-search/gotchas.md

@@ -0,0 +1,41 @@
+### Best Practices
+- Keep files under size limits
+- Use supported formats
+- Maintain valid Service API token
+- Clean up outdated content regularly
+- Monitor Vectorize index limits
+
+## Configuration via Dashboard
+
+### 1. Create Instance
+```
+Dashboard → AI Search → Create
+→ Choose data source (R2 bucket or Website)
+→ Configure settings
+→ Create
+```
+
+### 2. Monitor Indexing
+```
+AI Search → Select instance → Overview
+View: indexing status, progress, stats
+```
+
+### 3. Test Queries
+```
+AI Search → Select instance → Playground
+→ "Search with AI" or "Search"
+→ Enter query
+```
+
+### 4. Get API Token
+```
+AI Search → Select instance → Use AI Search → API
+→ Create API Token
+→ Permissions: "AI Search - Read", "AI Search Edit"
+```
+
+### 5. Connect to Application
+```
+AI Search → Select instance → Connect
+C

package/dist/template/.opencode/skill/cloudflare/references/ai-search/patterns.md

@@ -0,0 +1,45 @@
+## Common Use Cases
+
+1. **Enterprise search**: Natural language search over company docs
+2. **Customer support**: AI-powered chat with product documentation
+3. **Knowledge bases**: Semantic search over technical content
+4. **Multitenancy SaaS**: Per-tenant data isolation with folder filters
+5. **Content discovery**: Finding relevant content across large datasets
+
+## Workers Binding (Recommended)
+
+### Configuration
+
+**wrangler.toml:**
+```toml
+[ai]
+binding = "AI"
+```
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "ai": {
+    "binding": "AI"
+  }
+}
+```
+
+### Code Patterns
+
+#### AI Search with Generation
+```typescript
+// Generate AI response with retrieved context
+const answer = await env.AI.autorag("my-autorag").aiSearch({
+  query: "How do I configure rate limits?",
+  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+  rewrite_query: true,
+  max_num_results: 10,
+  ranking_options: {
+    score_threshold: 0.3
+  },
+  reranking: {
+    enabled: true,
+    model: "@cf/baai/bge-reranker-base"
+  },
+  stream: tr

package/dist/template/.opencode/skill/cloudflare/references/analytics-engine/README.md

@@ -0,0 +1,14 @@
+# Cloudflare Workers Analytics Engine Reference
+
+Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine. This skill covers ONLY Analytics Engine - NOT the broader Cloudflare platform....
+
+## 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/analytics-engine/api.md

@@ -0,0 +1,27 @@
+#### API Usage Tracking
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const customerId = request.headers.get("X-Customer-Id");
+    const startTime = Date.now();
+    
+    // Handle request...
+    const response = await handleRequest(request);
+    const duration = Date.now() - startTime;
+    
+    // Track API usage
+    env.API_USAGE.writeDataPoint({
+      blobs: [
+        url.pathname,                      // blob1: endpoint
+        request.method,                    // blob2: HTTP method  
+        response.status.toString(),        // blob3: status code
+        request.cf?.colo as string,        // blob4: datacenter
+        request.cf?.country as string      // blob5: country
+      ],
+      doubles: [
+        duration,                          // double1: latency ms
+        1                                  // double2: request count (for summing)
+      ],
+      indexes: [customerId || "anonymous"

package/dist/template/.opencode/skill/cloudflare/references/analytics-engine/configuration.md

@@ -0,0 +1,45 @@
+## Configuration
+
+### Wrangler Setup
+
+**wrangler.toml:**
+```toml
+[[analytics_engine_datasets]]
+binding = "WEATHER"
+dataset = "weather_data"
+```
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "analytics_engine_datasets": [
+    {
+      "binding": "WEATHER",
+      "dataset": "weather_data"
+    }
+  ]
+}
+```
+
+**Key Points:**
+- Datasets are created automatically on first write - no manual dashboard setup needed
+- `binding` = variable name accessible in Worker env
+- `dataset` = logical table name (like SQL table - rows/columns should have consistent meaning)
+- Multiple datasets can be defined per Worker
+
+### TypeScript Types
+
+```typescript
+interface Env {
+  WEATHER: AnalyticsEngineDataset;
+}
+
+// The binding exposes this interface
+interface AnalyticsEngineDataset {
+  writeDataPoint(data: AnalyticsEngineDataPoint): void;
+}
+
+interface AnalyticsEngineDataPoint {
+  blobs?: string[];      // Up to 20 strings (dimensions for grouping/filtering)
+  doubles?

package/dist/template/.opencode/skill/cloudflare/references/analytics-engine/gotchas.md

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

package/dist/template/.opencode/skill/cloudflare/references/analytics-engine/patterns.md

@@ -0,0 +1,36 @@
+### Common Use Cases
+
+1. **Custom customer-facing analytics** - Expose analytics dashboards to your users
+2. **Usage-based billing** - Track per-customer/per-feature usage for metered billing
+3. **Service health monitoring** - Per-customer/per-user health metrics
+4. **High-frequency instrumentation** - Add telemetry to hot code paths without performance impact
+5. **Event tracking** - User actions, API calls, errors, performance metrics
+
+## Configuration
+
+### Wrangler Setup
+
+**wrangler.toml:**
+```toml
+[[analytics_engine_datasets]]
+binding = "WEATHER"
+dataset = "weather_data"
+```
+
+**wrangler.jsonc:**
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "analytics_engine_datasets": [
+    {
+      "binding": "WEATHER",
+      "dataset": "weather_data"
+    }
+  ]
+}
+```
+
+**Key Points:**
+- Datasets are created automatically on first write - no manual dashboard setup needed
+- `binding` = variable name accessible in Worker env
+- `dataset` = logical table name (like SQL table - r

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

@@ -0,0 +1,21 @@
+# Cloudflare API Integration Skill Reference
+
+Guide for working with Cloudflare's REST API - covering authentication, SDK usage, common patterns, and API categories.
+
+## When to Use This Skill
+
+Use when working with:
+- Cloudflare API authentication and tokens
+- Official Cloudflare SDKs (TypeScript, Python, Go)
+- Zone management, DNS, Workers, o...
+
+## 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/api/api.md

@@ -0,0 +1,31 @@
+### API Token (Recommended)
+
+**Create token**: Dashboard → My Profile → API Tokens → Create Token
+
+```bash
+# Environment variable
+export CLOUDFLARE_API_TOKEN='your-token-here'
+
+# curl
+curl "https://api.cloudflare.com/client/v4/zones" \
+  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+**Token scopes**: Always use minimal permissions
+- Zone-specific vs account-level
+- Read vs edit permissions
+- Time-limited tokens for CI/CD
+
+### API Key (Legacy - Not Recommended)
+
+```bash
+curl "https://api.cloudflare.com/client/v4/zones" \
+  --header "X-Auth-Email: user@example.com" \
+  --header "X-Auth-Key: $CLOUDFLARE_API_KEY"
+```
+
+**Limitations**:
+- Full account access (insecure)
+- Cannot scope permissions
+- No expiration
+- Use tokens instead

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

@@ -0,0 +1,20 @@
+## Wrangler CLI Integration
+
+Wrangler uses Cloudflare API internally:
+
+```bash
+# Configure authentication
+wrangler login
+# Or
+export CLOUDFLARE_API_TOKEN='token'
+
+# Common commands that use API
+wrangler deploy              # Uploads worker via API
+wrangler kv:key put          # KV operations
+wrangler r2 bucket create    # R2 operations
+wrangler d1 execute          # D1 operations
+wrangler pages deploy        # Pages operations
+
+# Get API configuration
+wrangler whoami              # Shows authenticated user
+```

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

@@ -0,0 +1,28 @@
+## Best Practices
+
+### Security
+
+- **Never commit tokens**: Use environment variables
+- **Minimal permissions**: Create scoped API tokens
+- **Rotate tokens**: Regularly refresh tokens
+- **Use token expiration**: Set expiry dates
+- **Audit token usage**: Monitor API logs
+
+### Performance
+
+- **Batch operations**: Group related API calls
+- **Use pagination wisely**: Don't fetch all data if unnecessary
+- **Cache responses**: Store rarely-changing data locally
+- **Parallel requests**: Use `Promise.all()` for independent operations
+- **Handle rate limits**: Implement exponential backoff
+
+### Code organization
+
+```typescript
+// Create reusable client instance
+export const cfClient = new Cloudflare({
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+});
+
+// Wrap common operations
+export async function

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

@@ -0,0 +1,47 @@
+## Common API Categories
+
+### Zone Management
+
+```typescript
+// List zones (with filtering)
+const zones = await client.zones.list({
+  account: { id: 'account-id' },
+  status: 'active',
+});
+
+// Create zone
+const zone = await client.zones.create({
+  account: { id: 'account-id' },
+  name: 'example.com',
+  type: 'full', // or 'partial'
+});
+
+// Update zone
+await client.zones.edit('zone-id', {
+  paused: false,
+  vanity_name_servers: ['ns1.example.com', 'ns2.example.com'],
+});
+
+// Delete zone
+await client.zones.delete('zone-id');
+```
+
+### DNS Management
+
+```typescript
+// Create record
+await client.dns.records.create({
+  zone_id: 'zone-id',
+  type: 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'SRV',
+  name: 'subdomain.example.com',
+  content: '192.0.2.1',
+  ttl: 1, // 1 = auto, or specific seconds
+  proxied: true, // Orange cloud
+  priority: 10, // For MX/SRV records
+});
+
+// List records (with filtering)
+const records = await client.dns.records.list({
+  zone_id: 'zone-id',
+  type: 'A',
+  name: 'exa

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

@@ -0,0 +1,20 @@
+# Cloudflare API Shield Reference
+
+Expert guidance for API Shield - comprehensive API security suite for discovery, protection, and monitoring.
+
+## In This Reference
+
+- **[configuration.md](./configuration.md)** - Setup, session identifiers, rules, token/mTLS configs
+- **[api.md](./api.md)** - Endpoint management, discovery, validation APIs, GraphQL operations
+- **[patterns.md](./patterns.md)** - Common patterns, progressive rollout, OWASP mappings, workflows
+- **[gotchas.md](./gotchas.md)** - Troubleshooting, false positives, performance, best practices
+
+## Quick Start
+
+API Shield: Enterprise-grade API security (Discovery, Schema Validation, JWT, mTLS, Sequence Enforcement). Available as Enterprise add-on with preview access.
+
+## See Also
+
+- [API Shield Docs](https://developers.cloudflare.com/api-shield/)
+- [API Reference](https://developers.cloudflare.com/api/resources/api_gateway/)
+- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)

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

@@ -0,0 +1,78 @@
+# API Reference
+
+Base: `/zones/{zone_id}/api_gateway`
+
+## Endpoints
+
+```bash
+GET /operations                    # List
+GET /operations/{op_id}            # Get single
+POST /operations/item              # Create: {endpoint,host,method}
+POST /operations                   # Bulk: {operations:[{endpoint,host,method}]}
+DELETE /operations/{op_id}         # Delete
+DELETE /operations                 # Bulk delete: {operation_ids:[...]}
+```
+
+## Discovery
+
+```bash
+GET /discovery/operations                    # List discovered
+PATCH /discovery/operations/{op_id}          # Update: {state:"saved"|"ignored"}
+PATCH /discovery/operations                  # Bulk: {operation_ids:{id:{state}}}
+GET /discovery                               # OpenAPI export
+```
+
+## Config
+
+```bash
+GET /configuration        # Get session ID config
+PUT /configuration        # Update: {auth_id_characteristics:[{name,type:"header"|"cookie"}]}
+```
+
+## Token Validation
+
+```bash
+GET /token_validation                  # List
+POST /token_validation                 # Create: {name,location:{header:"..."},jwks:"..."}
+POST /jwt_validation_rules             # Rule: {name,hostname,token_validation_id,action:"block"}
+```
+
+## Workers
+
+API client:
+```js
+export default {
+  async fetch(req, env) {
+    const jwt = await generateJWT(env.JWT_SECRET);
+    return fetch('https://api.example.com/data', {
+      headers: {'Authorization': `Bearer ${jwt}`, 'Content-Type': 'application/json'}
+    });
+  }
+}
+```
+
+Dynamic JWKS:
+```js
+export default {
+  async scheduled(event, env) {
+    const jwks = await (await fetch('https://auth.example.com/.well-known/jwks.json')).json();
+    await fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/api_gateway/token_validation/${env.CONFIG_ID}`, {
+      method: 'PATCH',
+      headers: {'Authorization': `Bearer ${env.CF_API_TOKEN}`, 'Content-Type': 'application/json'},
+      body: JSON.stringify({jwks: JSON.stringify(jwks)})
+    });
+  }
+}
+```
+
+## Firewall Fields
+
+```js
+cf.api_gateway.auth_id_present           // Session ID present
+cf.api_gateway.request_violates_schema   // Schema violation
+cf.api_gateway.fallthrough_triggered     // No endpoint match
+cf.api_gateway.jwt_claims_valid          // JWT valid
+lookup_json_string(http.request.jwt.claims["{config_id}"][0], "claim_name")
+cf.tls_client_auth.cert_verified         // mTLS cert valid
+cf.tls_client_auth.cert_fingerprint_sha256
+```

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

@@ -0,0 +1,128 @@
+# Configuration
+
+## Schema Validation Setup
+
+**Upload schema (Dashboard):**
+```
+Security > API Shield > Schema validation > Add validation
+- Upload .yml/.yaml/.json (OpenAPI v3.0)
+- Endpoints auto-added to Endpoint Management
+- Action: Log/Block/None
+```
+
+**Change default action:**
+```
+Security > API Shield > Settings > Schema validation
+Per-endpoint: Filter → ellipses → Change action
+```
+
+**Fallthrough rule** (catch-all unknown endpoints):
+```
+Security > API Shield > Settings > Fallthrough > Use Template
+- Select hostnames
+- Create rule with cf.api_gateway.fallthrough_triggered
+```
+
+**Body inspection:** Supports `application/json`, `*/*`, `application/*`. Disable origin MIME sniffing to prevent bypasses.
+
+## JWT Validation
+
+**Setup token config:**
+```
+Security > API Shield > Settings > JWT Settings > Add configuration
+- Name: "Auth0 JWT Config"
+- Location: Header/Cookie + name (e.g., "Authorization")
+- JWKS: Paste public keys from IdP
+```
+
+**Create validation rule:**
+```
+Security > API Shield > API Rules > Add rule
+- Hostname: api.example.com
+- Deselect endpoints to ignore
+- Token config: Select config
+- Enforce presence: Ignore or Mark as non-compliant
+- Action: Log/Block/Challenge
+```
+
+**Rate limit by JWT claim:**
+```wirefilter
+lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
+```
+
+**Special cases:**
+- Two JWTs, different IdPs: Create 2 configs, select both, "Validate all"
+- IdP migration: 2 configs + 2 rules, adjust actions per state
+- Bearer prefix: API Shield handles with/without
+- Nested claims: Dot notation `user.email`
+
+## Mutual TLS (mTLS)
+
+**Setup:**
+```
+SSL/TLS > Client Certificates > Create Certificate
+- Generate CF-managed CA (all plans)
+- Upload custom CA (Enterprise, max 5)
+```
+
+**Configure mTLS rule:**
+```
+Security > API Shield > mTLS
+- Select hostname(s)
+- Choose certificate(s)
+- Action: Block/Log/Challenge
+```
+
+**Test:**
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365
+curl https://api.example.com/endpoint --cert client-cert.pem --key client-key.pem
+```
+
+## Session Identifiers
+
+Critical for Sequence Mitigation + analytics. Configure header/cookie that uniquely IDs API users.
+
+**Examples:** JWT sub claim, session token, API key, custom user ID header
+
+**Configure:**
+```
+Security > API Shield > Settings > Session Identifiers
+- Type: Header/Cookie
+- Name: "X-User-ID" or "Authorization"
+```
+
+## Terraform
+
+```hcl
+# Session identifier
+resource "cloudflare_api_shield" "main" {
+  zone_id = var.zone_id
+  auth_id_characteristics {
+    type = "header"
+    name = "Authorization"
+  }
+}
+
+# Add endpoint
+resource "cloudflare_api_shield_operation" "users_get" {
+  zone_id  = var.zone_id
+  method   = "GET"
+  host     = "api.example.com"
+  endpoint = "/api/users/{id}"
+}
+
+# JWT validation rule
+resource "cloudflare_ruleset" "jwt_validation" {
+  zone_id = var.zone_id
+  name    = "API JWT Validation"
+  kind    = "zone"
+  phase   = "http_request_firewall_custom"
+
+  rules {
+    action = "block"
+    expression = "(http.host eq \"api.example.com\" and not cf.api_gateway.jwt_claims_valid)"
+    description = "Block invalid JWTs"
+  }
+}
+```