opencodekit 0.15.3 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/network-interconnect/gotchas.md

@@ -0,0 +1,171 @@
+# CNI Gotchas & Troubleshooting
+
+See [README.md](./README.md) for overview.
+
+## Limitations
+
+**General:**
+- No formal SLA (free service)
+- No dashboard config visibility
+- Recovery may take days
+- 10km max optical distance
+- Backup Internet required
+
+**v1:**
+- Asymmetric MTU (1500↓/1476↑)
+- GRE overhead for Magic Transit/WAN
+- 1 Gbps/GRE tunnel limit
+
+**v2:**
+- No VLAN (yet)
+- No BFD (yet)
+- No LACP (use ECMP)
+- No peering support
+- Beta status
+
+**Cloud:**
+- AWS Hosted Direct Connect unsupported
+- Magic WAN only
+- GCP BGP routes ignored
+- AWS requires manual coordination
+
+## Troubleshooting
+
+### Status: Pending
+
+**Symptoms:** Stuck in pending.
+
+**Causes:**
+- Cross-connect not installed
+- RX/TX fibers reversed
+- Wrong fiber type
+- Low light levels
+
+**Fix:**
+1. Verify cross-connect installed
+2. Check fiber at patch panel
+3. Swap RX/TX
+4. Check light with optical power meter
+5. Contact account team
+
+### Status: Unhealthy
+
+**Symptoms:** Shows unhealthy.
+
+**Causes:**
+- Physical issue
+- Light <-20 dBm
+- Optic mismatch
+- Dirty connectors
+
+**Fix:**
+1. Check physical connections
+2. Clean fiber connectors
+3. Verify optic types (10GBASE-LR/100GBASE-LR4)
+4. Test with known-good optics
+5. Check patch panel
+6. Contact account team
+
+### BGP Session Down
+
+**Symptoms:** Link up, BGP down.
+
+**Causes:**
+- Wrong IP addressing
+- Wrong ASN
+- Password mismatch
+- Firewall blocking TCP/179
+
+**Fix:**
+1. Verify IPs match CNI object
+2. Confirm ASN correct
+3. Check BGP password
+4. Verify no firewall on TCP/179
+5. Check BGP logs
+6. Review BGP timers
+
+### Low Throughput
+
+**Symptoms:** Traffic flows, below expected.
+
+**Causes:**
+- MTU mismatch
+- Fragmentation
+- Single GRE tunnel (v1)
+- Routing inefficiency
+
+**Fix:**
+1. Check MTU (1500↓/1476↑ for v1, 1500 both for v2)
+2. Test various packet sizes
+3. Add more GRE tunnels (v1)
+4. Consider upgrading to v2
+5. Review routing tables
+6. Use LACP for bundling (v1)
+
+## Common Mistakes
+
+**Ordering:**
+- ❌ Wrong facility code on LOA
+- ❌ Multi-mode fiber (need single-mode)
+- ❌ Wrong optic type
+- ❌ Forgetting to track cross-connect order
+
+**Configuration:**
+- ❌ Not using /31 subnets
+- ❌ Skipping BGP passwords
+- ❌ Wrong ASN
+- ❌ Firewall blocking BGP (TCP/179)
+
+**Production:**
+- ❌ No maintenance notifications
+- ❌ Not testing backup connectivity
+- ❌ Missing runbooks
+- ❌ No failover testing
+- ❌ Ignoring capacity planning
+
+## Quick Reference
+
+**Status Guide:**
+- **Active**: Working normally → Monitor
+- **Unhealthy**: Down → Check physical
+- **Pending**: In progress → Complete cross-connect
+
+**Contact Account Team For:**
+- CNI eligibility
+- Config assistance
+- LOA generation
+- Unhealthy interconnects
+- Location availability
+- Device diversity options
+
+**Key Commands:**
+```bash
+# List interconnects
+curl "https://api.cloudflare.com/client/v4/accounts/${ID}/cni/interconnects" \
+  -H "Authorization: Bearer ${TOKEN}"
+
+# Get status
+curl "https://api.cloudflare.com/client/v4/accounts/${ID}/cni/interconnects/${ICON}/status" \
+  -H "Authorization: Bearer ${TOKEN}"
+
+# Download LOA
+curl "https://api.cloudflare.com/client/v4/accounts/${ID}/cni/interconnects/${ICON}/loa" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  --output loa.pdf
+
+# List CNI objects
+curl "https://api.cloudflare.com/client/v4/accounts/${ID}/cni/cnis" \
+  -H "Authorization: Bearer ${TOKEN}"
+
+# List available slots
+curl "https://api.cloudflare.com/client/v4/accounts/${ID}/cni/slots?occupied=false" \
+  -H "Authorization: Bearer ${TOKEN}"
+```
+
+## Resources
+
+- [CNI Overview](https://developers.cloudflare.com/network-interconnect/)
+- [Get Started](https://developers.cloudflare.com/network-interconnect/get-started/)
+- [Monitoring](https://developers.cloudflare.com/network-interconnect/monitoring-and-alerts/)
+- [Locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-30-10-2025.pdf)
+- [API Docs](https://developers.cloudflare.com/api/resources/network_interconnects/)

package/dist/template/.opencode/skill/cloudflare/references/network-interconnect/patterns.md

@@ -0,0 +1,171 @@
+# CNI Patterns
+
+See [README.md](./README.md) for overview.
+
+## High Availability
+
+**Critical:** Design for resilience from day one.
+
+**Requirements:**
+- Device-level diversity (separate hardware)
+- Backup Internet connectivity (no SLA on CNI)
+- Network-resilient locations preferred
+- Regular failover testing
+
+**Architecture:**
+```
+Your Network A ──10G CNI v2──> CF CCR Device 1
+                                     │
+Your Network B ──10G CNI v2──> CF CCR Device 2
+                                     │
+                            CF Global Network (AS13335)
+```
+
+**Capacity Planning:**
+- Plan across all links
+- Account for failover scenarios
+- Your responsibility
+
+## Pattern: Magic Transit + CNI v2
+
+**Use Case:** DDoS protection, private connectivity, no GRE overhead.
+
+```typescript
+// 1. Create interconnect
+const ic = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'magic-transit-primary',
+});
+
+// 2. Poll until active
+const status = await pollUntilActive(id, ic.id);
+
+// 3. Configure Magic Transit tunnel via Dashboard/API
+```
+
+**Benefits:** 1500 MTU both ways, simplified routing.
+
+## Pattern: Multi-Cloud Hybrid
+
+**Use Case:** AWS/GCP workloads with Cloudflare.
+
+**AWS Direct Connect:**
+```typescript
+// 1. Order Direct Connect in AWS Console
+// 2. Get LOA + VLAN from AWS
+// 3. Send to CF account team (no API)
+// 4. Configure static routes in Magic WAN
+
+await configureStaticRoutes(id, {
+  prefix: '10.0.0.0/8',
+  nexthop: 'aws-direct-connect',
+});
+```
+
+**GCP Cloud Interconnect:**
+```typescript
+// 1. Get VLAN pairing key from GCP
+// 2. Create via Dashboard (no SDK yet)
+// 3. Configure static routes in Magic WAN
+// 4. Configure BGP in GCP Cloud Router
+
+const ic = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'cloud',
+  cloud_provider: 'gcp',
+  pairing_key: 'gcp_key',
+  name: 'gcp-interconnect',
+});
+```
+
+## Pattern: Multi-Location HA
+
+**Use Case:** 99.99%+ uptime.
+
+```typescript
+// Primary (NY)
+const primary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'primary-ewr1',
+});
+
+// Secondary (NY, different hardware)
+const secondary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR2',
+  speed: '10G',
+  name: 'secondary-ewr2',
+});
+
+// Tertiary (LA, different geography)
+const tertiary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'partner',
+  facility: 'LAX1',
+  speed: '10G',
+  name: 'tertiary-lax1',
+});
+
+// BGP local preferences:
+// Primary: 200
+// Secondary: 150
+// Tertiary: 100
+// Internet: Last resort
+```
+
+## Pattern: Partner Interconnect (Equinix)
+
+**Use Case:** Quick deployment, no colocation.
+
+**Setup:**
+1. Order virtual circuit in Equinix Fabric Portal
+2. Select Cloudflare as destination
+3. Choose facility
+4. Send details to CF account team
+5. CF accepts in portal
+6. Configure BGP
+
+**No API automation** – partner portals managed separately.
+
+## Failover & Security
+
+**Failover Best Practices:**
+- Use BGP local preferences for priority
+- Configure BFD for fast detection (v1)
+- Test regularly with traffic shift
+- Document runbooks
+
+**Security:**
+- BGP password authentication
+- BGP route filtering
+- Monitor unexpected routes
+- Magic Firewall for DDoS/threats
+- Minimum API token permissions
+- Rotate credentials periodically
+
+## Decision Matrix
+
+| Requirement | Recommended |
+|-------------|-------------|
+| Collocated with CF | Direct |
+| Not collocated | Partner |
+| AWS/GCP workloads | Cloud |
+| 1500 MTU both ways | v2 |
+| VLAN tagging | v1 |
+| Public peering | v1 |
+| Simplest config | v2 |
+| BFD fast failover | v1 |
+| LACP bundling | v1 |
+
+## Resources
+
+- [Magic Transit Docs](https://developers.cloudflare.com/magic-transit/)
+- [Magic WAN Docs](https://developers.cloudflare.com/magic-wan/)
+- [Argo Smart Routing](https://developers.cloudflare.com/argo/)

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

@@ -0,0 +1,18 @@
+# Cloudflare Observability Skill Reference
+
+**Purpose**: Comprehensive guidance for implementing observability in Cloudflare Workers, covering traces, logs, metrics, and analytics.
+
+**Scope**: Cloudflare Observability features ONLY - Workers Logs, Traces, Analytics Engine, Logpush, Metrics & Analytics, and OpenTelemetry exports.
+
+---...
+
+## 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/observability/api.md

@@ -0,0 +1,51 @@
+## API Reference
+
+### GraphQL Analytics API
+
+**Endpoint**: `https://api.cloudflare.com/client/v4/graphql`
+
+**Query Workers Metrics**:
+```graphql
+query {
+  viewer {
+    accounts(filter: { accountTag: $accountId }) {
+      workersInvocationsAdaptive(
+        limit: 100
+        filter: {
+          datetime_geq: "2025-01-01T00:00:00Z"
+          datetime_leq: "2025-01-31T23:59:59Z"
+          scriptName: "my-worker"
+        }
+      ) {
+        sum {
+          requests
+          errors
+          subrequests
+        }
+        quantiles {
+          cpuTimeP50
+          cpuTimeP99
+          wallTimeP50
+          wallTimeP99
+        }
+      }
+    }
+  }
+}
+```
+
+### Analytics Engine SQL API
+
+**Endpoint**: `https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql`
+
+**Authentication**: `Authorization: Bearer <API_TOKEN>` (Account Analytics Read permission)
+
+**Common Queries**:
+
+```sql
+-- List all datasets
+SHOW TABLES;
+
+-- Time-series aggregation (5-minute buckets)
+SELECT
+  intDi

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

@@ -0,0 +1,60 @@
+## Configuration Patterns
+
+### Enable Workers Logs
+
+```jsonc
+// wrangler.jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1  // 100% sampling (default)
+  }
+}
+```
+
+```toml
+# wrangler.toml
+[observability]
+enabled = true
+head_sampling_rate = 1  # 100% sampling
+```
+
+**Best Practice**: Use structured JSON logging for better indexing
+
+```typescript
+// Good - structured logging
+console.log({ 
+  user_id: 123, 
+  action: "login", 
+  status: "success",
+  duration_ms: 45
+});
+
+// Avoid - unstructured string
+console.log("user_id: 123 logged in successfully in 45ms");
+```
+
+### Enable Workers Traces
+
+```jsonc
+// wrangler.jsonc
+{
+  "observability": {
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.05  // 5% sampling
+    }
+  }
+}
+```
+
+```toml
+# wrangler.toml
+[observability.traces]
+enabled = true
+head_sampling_rate = 0.05  # 5% sampling
+```
+
+**Note**: Default sampling is 100%. For high-traffic Workers, use lower sampling (0.01-0.1).
+
+### Configure Analytics

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

@@ -0,0 +1,36 @@
+## Troubleshooting
+
+### Logs not appearing
+
+**Check**:
+1. `observability.enabled = true` in wrangler config
+2. Worker has been redeployed after config change
+3. Worker is receiving traffic
+4. Sampling rate is not too low (check `head_sampling_rate`)
+5. Log size under 256 KB limit
+
+**Solution**:
+```bash
+# Verify config
+cat wrangler.toml | grep -A 5 observability
+
+# Check deployment
+wrangler deployments list <WORKER_NAME>
+
+# Test with curl
+curl https://your-worker.workers.dev
+```
+
+### Traces not being captured
+
+**Check**:
+1. `observability.traces.enabled = true`
+2. `head_sampling_rate` is appropriate (1.0 for testing)
+3. Worker deployed after traces enabled
+4. Check destination status in dashboard
+
+**Solution**:
+```jsonc
+// Temporarily set to 100% sampling for debugging
+{
+  "observability": 

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

@@ -0,0 +1,42 @@
+## Common Use Cases
+
+### 1. Usage-Based Billing
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const customerId = request.headers.get('X-Customer-ID');
+    const apiKey = request.headers.get('X-API-Key');
+    
+    if (!customerId || !apiKey) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    
+    // Track API usage per customer
+    env.ANALYTICS.writeDataPoint({
+      'blobs': [customerId, request.url, request.method],
+      'doubles': [1], // request_count
+      'indexes': [customerId]
+    });
+    
+    return processRequest(request);
+  }
+}
+```
+
+**Query for billing**:
+```sql
+SELECT
+  blob1 AS customer_id,
+  SUM(_sample_interval * double1) AS total_api_calls
+FROM api_usage
+WHERE timestamp >= DATE_TRUNC('month', NOW())
+GROUP BY customer_id
+ORDER BY total_api_calls DESC
+```
+
+### 2. Performance Monitoring
+
+```typescript
+async function monitoredFetch(url: string, env: Env): Promise<Response> {
+  const start = Date.now(

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

@@ -0,0 +1,76 @@
+# Cloudflare Pages
+
+JAMstack platform for full-stack apps on Cloudflare's global network.
+
+## Key Features
+
+- **Git-based deploys**: Auto-deploy from GitHub/GitLab
+- **Preview deployments**: Unique URL per branch/PR
+- **Pages Functions**: File-based serverless routing (Workers runtime)
+- **Static + dynamic**: Smart asset caching + edge compute
+- **Framework optimized**: Next.js, SvelteKit, Remix, Astro, Nuxt, Qwik
+
+## Deployment Methods
+
+### 1. Git Integration (Production)
+Dashboard → Workers & Pages → Create → Connect to Git → Configure build
+
+### 2. Direct Upload
+```bash
+npx wrangler pages deploy ./dist --project-name=my-project
+npx wrangler pages deploy ./dist --project-name=my-project --branch=staging
+```
+
+### 3. C3 CLI
+```bash
+npm create cloudflare@latest my-app
+# Select framework → auto-setup + deploy
+```
+
+## vs Workers
+
+- **Pages**: Static sites, JAMstack, frameworks, git workflow, file-based routing
+- **Workers**: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers
+- **Combine**: Pages Functions use Workers runtime, can bind to Workers
+
+## Quick Start
+
+```bash
+# Create
+npm create cloudflare@latest
+
+# Local dev
+npx wrangler pages dev ./dist
+
+# Deploy
+npx wrangler pages deploy ./dist --project-name=my-project
+
+# Types
+npx wrangler types --path='./functions/types.d.ts'
+
+# Secrets
+echo "value" | npx wrangler pages secret put KEY --project-name=my-project
+
+# Logs
+npx wrangler pages deployment tail --project-name=my-project
+```
+
+## Resources
+
+- [Pages Docs](https://developers.cloudflare.com/pages/)
+- [Functions API](https://developers.cloudflare.com/pages/functions/api-reference/)
+- [Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
+- [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc, build, env vars
+- [api.md](./api.md) - Functions API, bindings, context
+- [patterns.md](./patterns.md) - Full-stack patterns, frameworks
+- [gotchas.md](./gotchas.md) - Build issues, limits, debugging
+
+## See Also
+
+- [pages-functions](../pages-functions/) - File-based routing, middleware
+- [d1](../d1/) - SQL database for Pages Functions
+- [kv](../kv/) - Key-value storage for caching/state