memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/argo-smart-routing/configuration.md

@@ -0,0 +1,205 @@
+## Configuration Management
+
+**Note on Smart Shield Evolution:** Argo Smart Routing is being integrated into Smart Shield. Configuration methods below remain valid; Terraform and IaC patterns unchanged.
+
+### 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,
+      threshold: 100, // GB
+    },
+  },
+  development: {
+    enabled: false,
+    tieredCache: false,
+    monitoring: {
+      usageAlerts: false,
+      threshold: 0,
+    },
+  },
+}
+
+export function getArgoConfig(env: string): ArgoEnvironmentConfig {
+  return configs[env] || configs.development
+}
+```
+
+### Pulumi Configuration
+
+```typescript
+// pulumi/argo.ts
+import * as cloudflare from '@pulumi/cloudflare'
+
+const zone = new cloudflare.Zone('example-zone', {
+  zone: 'example.com',
+  plan: 'enterprise',
+})
+
+const argoSettings = new cloudflare.Argo('argo-config', {
+  zoneId: zone.id,
+  smartRouting: 'on',
+  tieredCaching: 'on',
+})
+
+export const argoEnabled = argoSettings.smartRouting
+export const zoneId = zone.id
+```
+
+## Billing Configuration
+
+Before enabling Argo Smart Routing, ensure billing is configured for the account:
+
+**Prerequisites:**
+
+1. Valid payment method on file
+2. Enterprise or higher plan
+3. Zone must have billing enabled
+
+**Check Billing Status via Dashboard:**
+
+1. Navigate to Account → Billing
+2. Verify payment method configured
+3. Check zone subscription status
+
+**Note:** Attempting to enable Argo without billing configured will result in `editable: false` in API responses.
+
+## Environment Variable Setup
+
+**Required Environment Variables:**
+
+```bash
+# .env
+CLOUDFLARE_API_TOKEN=your_api_token_here
+CLOUDFLARE_ZONE_ID=your_zone_id_here
+CLOUDFLARE_ACCOUNT_ID=your_account_id_here
+
+# Optional
+ARGO_ENABLED=true
+ARGO_TIERED_CACHE=true
+```
+
+**TypeScript Configuration Loader:**
+
+```typescript
+// config/env.ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  CLOUDFLARE_API_TOKEN: z.string().min(1),
+  CLOUDFLARE_ZONE_ID: z.string().min(1),
+  CLOUDFLARE_ACCOUNT_ID: z.string().min(1),
+  ARGO_ENABLED: z.string().optional().default('false'),
+  ARGO_TIERED_CACHE: z.string().optional().default('false'),
+})
+
+export const env = envSchema.parse(process.env)
+
+export const argoConfig = {
+  enabled: env.ARGO_ENABLED === 'true',
+  tieredCache: env.ARGO_TIERED_CACHE === 'true',
+}
+```
+
+## CI/CD Integration
+
+**GitHub Actions Example:**
+
+```yaml
+# .github/workflows/deploy-argo.yml
+name: Deploy Argo Configuration
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'terraform/argo.tf'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v2
+
+      - name: Terraform Init
+        run: terraform init
+        working-directory: ./terraform
+
+      - name: Terraform Apply
+        run: terraform apply -auto-approve
+        working-directory: ./terraform
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          TF_VAR_zone_id: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+```
+
+## Enterprise Preview Program
+
+For early access to Argo Smart Routing features and Smart Shield integration:
+
+**Eligibility:**
+
+- Enterprise plan customers
+- Active Cloudflare support contract
+- Production traffic >100GB/month
+
+**How to Join:**
+
+1. Contact Cloudflare account team or support
+2. Request Argo/Smart Shield preview access
+3. Receive preview zone configuration
+
+**Preview Features:**
+
+- Enhanced analytics and reporting
+- Smart Shield DDoS integration
+- Advanced routing policies
+- Priority support for routing issues

package/skills/cloudflare/references/argo-smart-routing/gotchas.md

@@ -0,0 +1,115 @@
+## Best Practices Summary
+
+**Smart Shield Note:** Argo Smart Routing evolving into Smart Shield. Best practices below remain applicable; monitor Cloudflare changelog for Smart Shield updates.
+
+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
+
+## Common Errors
+
+### "Argo unavailable"
+
+**Problem:** API returns error "Argo Smart Routing is unavailable for this zone"
+
+**Cause:** Zone not eligible or billing not set up
+
+**Solution:**
+
+1. Verify zone has Enterprise or higher plan
+2. Check billing is configured in Account → Billing
+3. Ensure payment method is valid and current
+4. Contact Cloudflare support if eligibility unclear
+
+### "Cannot enable/disable"
+
+**Problem:** API call succeeds but status remains unchanged, or `editable: false` in GET response
+
+**Cause:** Insufficient permissions or zone restrictions
+
+**Solution:**
+
+1. Check API token has `Zone:Argo Smart Routing:Edit` permission
+2. Verify `editable: true` in GET response before attempting PATCH
+3. If `editable: false`, check:
+   - Billing configured for account
+   - Zone plan includes Argo (Enterprise+)
+   - No active zone holds or suspensions
+   - API token has correct scopes
+
+### `editable: false` Error
+
+**Problem:** GET request returns `"editable": false`, preventing enable/disable
+
+**Cause:** Zone-level restrictions from billing, plan, or permissions
+
+**Solution Pattern:**
+
+```typescript
+const status = await client.argo.smartRouting.get({ zone_id: zoneId })
+
+if (!status.editable) {
+  // Don't attempt to modify - will fail
+  console.error('Cannot modify Argo settings:')
+  console.error('- Check billing is configured')
+  console.error('- Verify zone has Enterprise+ plan')
+  console.error('- Confirm API token has Edit permission')
+  throw new Error('Argo is not editable for this zone')
+}
+
+// Safe to proceed with enable/disable
+await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' })
+```
+
+### Rate Limiting
+
+**Problem:** `429 Too Many Requests` error from API
+
+**Cause:** Exceeded API rate limits (typically 1200 requests per 5 minutes)
+
+**Solution:**
+
+```typescript
+import { RateLimitError } from 'cloudflare'
+
+try {
+  await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' })
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    const retryAfter = error.response?.headers.get('retry-after')
+    console.log(`Rate limited. Retry after ${retryAfter} seconds`)
+
+    // Implement exponential backoff
+    await new Promise((resolve) => setTimeout(resolve, (retryAfter || 60) * 1000))
+    // Retry request
+  }
+}
+```
+
+## Limits
+
+| Resource/Limit             | Value              | Notes                                   |
+| -------------------------- | ------------------ | --------------------------------------- |
+| Min requests for analytics | 500 in 48h         | For detailed metrics via GraphQL        |
+| Zones supported            | Enterprise+        | Check zone plan in dashboard            |
+| Billing requirement        | Must be configured | Before enabling; verify payment method  |
+| API rate limit             | 1200 req / 5 min   | Per API token across all endpoints      |
+| Spectrum apps              | No hard limit      | Each app can enable Argo independently  |
+| Traffic counting           | Proxied only       | Only orange-clouded DNS records count   |
+| DDoS/WAF exemption         | Yes                | Mitigated traffic excluded from billing |
+| Analytics latency          | 1-5 minutes        | Real-time metrics not available         |
+
+## Additional Resources
+
+- [Official Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)
+- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)
+- [API Authentication](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
+- [Cloudflare TypeScript SDK](https://github.com/cloudflare/cloudflare-typescript)
+- [Cloudflare Python SDK](https://github.com/cloudflare/cloudflare-python)

package/skills/cloudflare/references/argo-smart-routing/patterns.md

@@ -0,0 +1,107 @@
+# Integration Patterns
+
+## Enable Argo + Tiered Cache
+
+```typescript
+async function enableOptimalPerformance(client: Cloudflare, zoneId: string) {
+  await Promise.all([
+    client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),
+    client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),
+  ])
+}
+```
+
+**Flow:** Visitor → Edge (Lower-Tier) → [Cache Miss] → Upper-Tier → [Cache Miss + Argo] → Origin
+
+**Impact:** Argo ~30% latency reduction + Tiered Cache 50-80% origin offload
+
+## Usage Analytics (GraphQL)
+
+```graphql
+query ArgoAnalytics($zoneTag: string!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequestsAdaptiveGroups(limit: 1000) {
+        sum {
+          argoBytes
+          bytes
+        }
+      }
+    }
+  }
+}
+```
+
+**Billing:** ~$0.10/GB. DDoS-mitigated and WAF-blocked traffic NOT charged.
+
+## Spectrum TCP Integration
+
+Enable Argo for non-HTTP traffic (databases, game servers, IoT):
+
+```typescript
+// Update existing app
+await client.spectrum.apps.update(appId, { zone_id: zoneId, argo_smart_routing: true })
+
+// Create new app with Argo
+await client.spectrum.apps.create({
+  zone_id: zoneId,
+  dns: { type: 'CNAME', name: 'tcp.example.com' },
+  origin_direct: ['tcp://origin.example.com:3306'],
+  protocol: 'tcp/3306',
+  argo_smart_routing: true,
+})
+```
+
+**Use cases:** MySQL/PostgreSQL (3306/5432), game servers, MQTT (1883), SSH (22)
+
+## Pre-Flight Validation
+
+```typescript
+async function validateArgoEligibility(client: Cloudflare, zoneId: string) {
+  const status = await client.argo.smartRouting.get({ zone_id: zoneId })
+  const zone = await client.zones.get({ zone_id: zoneId })
+
+  const issues: string[] = []
+  if (!status.editable) issues.push('Zone not editable')
+  if (['free', 'pro'].includes(zone.plan.legacy_id)) issues.push('Requires Business+ plan')
+  if (zone.status !== 'active') issues.push('Zone not active')
+
+  return { canEnable: issues.length === 0, issues }
+}
+```
+
+## Post-Enable Verification
+
+```typescript
+async function verifyArgoEnabled(client: Cloudflare, zoneId: string): Promise<boolean> {
+  await new Promise((r) => setTimeout(r, 2000)) // Wait for propagation
+  const status = await client.argo.smartRouting.get({ zone_id: zoneId })
+  return status.value === 'on'
+}
+```
+
+## Full Setup Pattern
+
+```typescript
+async function setupArgo(client: Cloudflare, zoneId: string) {
+  // 1. Validate
+  const { canEnable, issues } = await validateArgoEligibility(client, zoneId)
+  if (!canEnable) throw new Error(issues.join(', '))
+
+  // 2. Enable both features
+  await Promise.all([
+    client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' }),
+    client.argo.tieredCaching.edit({ zone_id: zoneId, value: 'on' }),
+  ])
+
+  // 3. Verify
+  const [argo, cache] = await Promise.all([
+    client.argo.smartRouting.get({ zone_id: zoneId }),
+    client.argo.tieredCaching.get({ zone_id: zoneId }),
+  ])
+
+  return { argo: argo.value === 'on', tieredCache: cache.value === 'on' }
+}
+```
+
+**When to combine:** High-traffic sites (>1TB/mo), global users, cacheable content.

package/skills/cloudflare/references/bindings/README.md

@@ -0,0 +1,127 @@
+# Cloudflare Bindings Skill Reference
+
+Expert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources.
+
+## What Are Bindings?
+
+Bindings 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.
+
+## Reading Order
+
+1. **This file** - Binding catalog and selection guide
+2. **[api.md](api.md)** - TypeScript types and env access patterns
+3. **[configuration.md](configuration.md)** - Complete wrangler.jsonc examples
+4. **[patterns.md](patterns.md)** - Best practices and common patterns
+5. **[gotchas.md](gotchas.md)** - Critical pitfalls and troubleshooting
+
+## Binding Catalog
+
+### Storage Bindings
+
+| Binding             | Use Case                          | Access Pattern                |
+| ------------------- | --------------------------------- | ----------------------------- |
+| **KV**              | Key-value cache, CDN-backed reads | `env.MY_KV.get(key)`          |
+| **R2**              | Object storage (S3-compatible)    | `env.MY_BUCKET.get(key)`      |
+| **D1**              | SQL database (SQLite)             | `env.DB.prepare(sql).all()`   |
+| **Durable Objects** | Coordination, real-time state     | `env.MY_DO.get(id)`           |
+| **Vectorize**       | Vector embeddings search          | `env.VECTORIZE.query(vector)` |
+| **Queues**          | Async message processing          | `env.MY_QUEUE.send(msg)`      |
+
+### Compute Bindings
+
+| Binding               | Use Case             | Access Pattern              |
+| --------------------- | -------------------- | --------------------------- |
+| **Service**           | Worker-to-Worker RPC | `env.MY_SERVICE.fetch(req)` |
+| **Workers AI**        | LLM inference        | `env.AI.run(model, input)`  |
+| **Browser Rendering** | Headless Chrome      | `env.BROWSER.fetch(url)`    |
+
+### Platform Bindings
+
+| Binding              | Use Case               | Access Pattern                       |
+| -------------------- | ---------------------- | ------------------------------------ |
+| **Analytics Engine** | Custom metrics         | `env.ANALYTICS.writeDataPoint(data)` |
+| **mTLS**             | Client certificates    | `env.MY_CERT` (string)               |
+| **Hyperdrive**       | Database pooling       | `env.HYPERDRIVE.connectionString`    |
+| **Rate Limiting**    | Request throttling     | `env.RATE_LIMITER.limit(id)`         |
+| **Workflows**        | Long-running workflows | `env.MY_WORKFLOW.create()`           |
+
+### Configuration Bindings
+
+| Binding                   | Use Case             | Access Pattern                     |
+| ------------------------- | -------------------- | ---------------------------------- |
+| **Environment Variables** | Non-sensitive config | `env.API_URL` (string)             |
+| **Secrets**               | Sensitive values     | `env.API_KEY` (string)             |
+| **Text/Data Blobs**       | Static files         | `env.MY_BLOB` (string)             |
+| **WASM**                  | WebAssembly modules  | `env.MY_WASM` (WebAssembly.Module) |
+
+## Quick Selection Guide
+
+**Need persistent storage?**
+
+- Key-value < 25MB → **KV**
+- Files/objects → **R2**
+- Relational data → **D1**
+- Real-time coordination → **Durable Objects**
+
+**Need AI/compute?**
+
+- LLM inference → **Workers AI**
+- Scraping/PDFs → **Browser Rendering**
+- Call another Worker → **Service binding**
+
+**Need async processing?**
+
+- Background jobs → **Queues**
+
+**Need config?**
+
+- Public values → **Environment Variables**
+- Secrets → **Secrets** (never commit)
+
+## Quick Start
+
+1. **Add binding to wrangler.jsonc:**
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "your-kv-id" }],
+}
+```
+
+2. **Generate types:**
+
+```bash
+npx wrangler types
+```
+
+3. **Access in Worker:**
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    await env.MY_KV.put('key', 'value')
+    return new Response('OK')
+  },
+}
+```
+
+## Type Safety
+
+Bindings are fully typed via `wrangler types`. See [api.md](api.md) for details.
+
+## Limits
+
+- 64 bindings max per Worker (all types combined)
+- See [gotchas.md](gotchas.md) for per-binding limits
+
+## Key Concepts
+
+**Zero-overhead access:** Bindings compiled into Worker, no network calls to access
+**Type-safe:** Full TypeScript support via `wrangler types`
+**Per-environment:** Different IDs for dev/staging/production
+**Secrets vs Vars:** Secrets encrypted at rest, never in config files
+
+## See Also
+
+- [Cloudflare Docs: Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/)
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)