ai-qakit 1.0.0

package/templates/.claude/skills/infra-engineer/references/cloudflare-platform.md

@@ -0,0 +1,271 @@
+# Cloudflare Platform Overview
+
+Cloudflare Developer Platform: comprehensive edge computing ecosystem for full-stack applications on global network across 300+ cities.
+
+## Core Concepts
+
+### Edge Computing Model
+
+**Global Network:**
+- Code runs on servers in 300+ cities globally
+- Requests execute from nearest location
+- Ultra-low latency (<50ms typical)
+- Automatic failover and redundancy
+
+**V8 Isolates:**
+- Lightweight execution environments (faster than containers)
+- Millisecond cold starts
+- Zero infrastructure management
+- Automatic scaling
+- Pay-per-request pricing
+
+### Key Components
+
+**Workers** - Serverless functions on edge
+- HTTP/scheduled/queue/email handlers
+- JavaScript/TypeScript/Python/Rust support
+- Max 50ms CPU (free), 30s (paid)
+- 128MB memory limit
+
+**D1** - SQLite database with global read replication
+- Standard SQLite syntax
+- Single-writer consistency
+- Global read replication
+- 25GB database size limit
+- Batch operations for transactions
+
+**KV** - Distributed key-value store
+- Sub-millisecond reads (edge-cached)
+- Eventual consistency (~60s globally)
+- 25MB value size limit
+- Automatic TTL expiration
+- Best for: cache, sessions, feature flags
+
+**R2** - Object storage (S3-compatible)
+- Zero egress fees (huge cost advantage)
+- Unlimited storage
+- 5TB object size limit
+- S3-compatible API
+- Multipart upload support
+
+**Durable Objects** - Stateful compute with WebSockets
+- Single-instance coordination (strong consistency)
+- Persistent storage (1GB limit paid)
+- WebSocket support
+- Automatic hibernation
+
+**Queues** - Message queue system
+- At-least-once delivery
+- Automatic retries (exponential backoff)
+- Dead-letter queue support
+- Batch processing
+
+**Pages** - Static site hosting + serverless functions
+- Git integration (auto-deploy)
+- Directory-based routing
+- Framework support (Next.js, Remix, Astro, SvelteKit)
+- Built-in preview deployments
+
+**Workers AI** - Run AI models on edge
+- LLMs (Llama 3, Mistral, Gemma, Qwen)
+- Image generation (Stable Diffusion, DALL-E)
+- Embeddings (BGE, GTE)
+- Speech recognition (Whisper)
+- No GPU management required
+
+**Browser Rendering** - Headless browser automation
+- Puppeteer/Playwright support
+- Screenshots, PDFs, web scraping
+- Session reuse for cost optimization
+- MCP server support for AI agents
+
+## Architecture Patterns
+
+### Full-Stack Application
+
+```
+┌─────────────────────────────────────────┐
+│    Cloudflare Pages (Frontend)          │
+│    Next.js / Remix / Astro               │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│    Workers (API Layer)                   │
+│    - Routing                             │
+│    - Authentication                      │
+│    - Business logic                      │
+└─┬──────┬──────┬──────┬──────┬───────────┘
+  │      │      │      │      │
+  ▼      ▼      ▼      ▼      ▼
+┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────────────┐
+│ D1 │ │ KV │ │ R2 │ │ DO │ │ Workers AI │
+└────┘ └────┘ └────┘ └────┘ └────────────┘
+```
+
+### Polyglot Storage Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    // KV: Fast cache
+    const cached = await env.KV.get(key);
+    if (cached) return new Response(cached);
+
+    // D1: Structured data
+    const user = await env.DB.prepare(
+      "SELECT * FROM users WHERE id = ?"
+    ).bind(userId).first();
+
+    // R2: Media files
+    const avatar = await env.R2_BUCKET.get(`avatars/${user.id}.jpg`);
+
+    // Durable Objects: Real-time
+    const chat = env.CHAT_ROOM.get(env.CHAT_ROOM.idFromName(roomId));
+
+    // Queue: Async processing
+    await env.EMAIL_QUEUE.send({ to: user.email, template: 'welcome' });
+
+    return new Response(JSON.stringify({ user }));
+  }
+};
+```
+
+## Wrangler CLI Essentials
+
+### Installation
+```bash
+npm install -g wrangler
+wrangler login
+wrangler init my-worker
+```
+
+### Core Commands
+```bash
+# Development
+wrangler dev                    # Local dev server
+wrangler dev --remote          # Dev on real edge
+
+# Deployment
+wrangler deploy                # Deploy to production
+wrangler deploy --dry-run      # Preview changes
+
+# Logs
+wrangler tail                  # Real-time logs
+wrangler tail --format pretty  # Formatted logs
+
+# Versions
+wrangler deployments list      # List deployments
+wrangler rollback [version]    # Rollback
+
+# Secrets
+wrangler secret put SECRET_NAME
+wrangler secret list
+```
+
+### Resource Management
+```bash
+# D1
+wrangler d1 create my-db
+wrangler d1 execute my-db --file=schema.sql
+
+# KV
+wrangler kv:namespace create MY_KV
+wrangler kv:key put --binding=MY_KV "key" "value"
+
+# R2
+wrangler r2 bucket create my-bucket
+wrangler r2 object put my-bucket/file.txt --file=./file.txt
+```
+
+## Configuration (wrangler.toml)
+
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+# Environment variables
+[vars]
+ENVIRONMENT = "production"
+
+# D1 Database
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "YOUR_DATABASE_ID"
+
+# KV Namespace
+[[kv_namespaces]]
+binding = "KV"
+id = "YOUR_NAMESPACE_ID"
+
+# R2 Bucket
+[[r2_buckets]]
+binding = "R2_BUCKET"
+bucket_name = "my-bucket"
+
+# Durable Objects
+[[durable_objects.bindings]]
+name = "COUNTER"
+class_name = "Counter"
+script_name = "my-worker"
+
+# Queues
+[[queues.producers]]
+binding = "MY_QUEUE"
+queue = "my-queue"
+
+# Workers AI
+[ai]
+binding = "AI"
+
+# Cron triggers
+[triggers]
+crons = ["0 0 * * *"]
+```
+
+## Best Practices
+
+### Performance
+- Keep Workers lightweight (<1MB bundled)
+- Use bindings over fetch (faster than HTTP)
+- Leverage KV and Cache API for frequently accessed data
+- Use D1 batch for multiple queries
+- Stream large responses
+
+### Security
+- Use `wrangler secret` for API keys
+- Separate production/staging/development environments
+- Validate user input
+- Implement rate limiting (KV or Durable Objects)
+- Configure proper CORS headers
+
+### Cost Optimization
+- R2 for large files (zero egress fees vs S3)
+- KV for caching (reduce D1/R2 requests)
+- Request deduplication with caching
+- Efficient D1 queries (proper indexing)
+- Monitor usage via Cloudflare Analytics
+
+## Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| Sub-millisecond reads | KV |
+| SQL queries | D1 |
+| Large files (>25MB) | R2 |
+| Real-time WebSockets | Durable Objects |
+| Async background jobs | Queues |
+| ACID transactions | D1 |
+| Strong consistency | Durable Objects |
+| Zero egress costs | R2 |
+| AI inference | Workers AI |
+| Static site hosting | Pages |
+
+## Resources
+
+- Docs: https://developers.cloudflare.com
+- Wrangler: https://developers.cloudflare.com/workers/wrangler/
+- Discord: https://discord.cloudflare.com
+- Examples: https://developers.cloudflare.com/workers/examples/
+- Status: https://www.cloudflarestatus.com

package/templates/.claude/skills/infra-engineer/references/cloudflare-r2-storage.md

@@ -0,0 +1,280 @@
+# Cloudflare R2 Storage
+
+S3-compatible object storage with zero egress fees.
+
+## Quick Start
+
+### Create Bucket
+```bash
+wrangler r2 bucket create my-bucket
+wrangler r2 bucket create my-bucket --location=wnam
+```
+
+Locations: `wnam`, `enam`, `weur`, `eeur`, `apac`
+
+### Upload Object
+```bash
+wrangler r2 object put my-bucket/file.txt --file=./local-file.txt
+```
+
+### Workers Binding
+
+**wrangler.toml:**
+```toml
+[[r2_buckets]]
+binding = "MY_BUCKET"
+bucket_name = "my-bucket"
+```
+
+**Worker:**
+```typescript
+// Put
+await env.MY_BUCKET.put('user-uploads/photo.jpg', imageData, {
+  httpMetadata: {
+    contentType: 'image/jpeg',
+    cacheControl: 'public, max-age=31536000'
+  },
+  customMetadata: {
+    uploadedBy: userId,
+    uploadDate: new Date().toISOString()
+  }
+});
+
+// Get
+const object = await env.MY_BUCKET.get('large-file.mp4');
+if (!object) {
+  return new Response('Not found', { status: 404 });
+}
+
+return new Response(object.body, {
+  headers: {
+    'Content-Type': object.httpMetadata.contentType,
+    'ETag': object.etag
+  }
+});
+
+// List
+const listed = await env.MY_BUCKET.list({
+  prefix: 'user-uploads/',
+  limit: 100
+});
+
+// Delete
+await env.MY_BUCKET.delete('old-file.txt');
+
+// Head (check existence)
+const object = await env.MY_BUCKET.head('file.txt');
+if (object) {
+  console.log('Size:', object.size);
+}
+```
+
+## S3 API Integration
+
+### AWS CLI
+```bash
+# Configure
+aws configure
+# Access Key ID: <your-key-id>
+# Secret Access Key: <your-secret>
+# Region: auto
+
+# Operations
+aws s3api list-buckets --endpoint-url https://<accountid>.r2.cloudflarestorage.com
+
+aws s3 cp file.txt s3://my-bucket/ --endpoint-url https://<accountid>.r2.cloudflarestorage.com
+
+# Presigned URL
+aws s3 presign s3://my-bucket/file.txt --endpoint-url https://<accountid>.r2.cloudflarestorage.com --expires-in 3600
+```
+
+### JavaScript (AWS SDK v3)
+```javascript
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+
+const s3 = new S3Client({
+  region: "auto",
+  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+  credentials: {
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY
+  }
+});
+
+await s3.send(new PutObjectCommand({
+  Bucket: "my-bucket",
+  Key: "file.txt",
+  Body: fileContents
+}));
+```
+
+### Python (Boto3)
+```python
+import boto3
+
+s3 = boto3.client(
+    service_name='s3',
+    endpoint_url=f'https://{account_id}.r2.cloudflarestorage.com',
+    aws_access_key_id=access_key_id,
+    aws_secret_access_key=secret_access_key,
+    region_name='auto'
+)
+
+s3.upload_fileobj(file_obj, 'my-bucket', 'file.txt')
+s3.download_file('my-bucket', 'file.txt', './local-file.txt')
+```
+
+## Multipart Uploads
+
+For files >100MB:
+
+```typescript
+const multipart = await env.MY_BUCKET.createMultipartUpload('large-file.mp4');
+
+// Upload parts (5MiB - 5GiB each, max 10,000 parts)
+const part1 = await multipart.uploadPart(1, chunk1);
+const part2 = await multipart.uploadPart(2, chunk2);
+
+// Complete
+const object = await multipart.complete([part1, part2]);
+```
+
+### Rclone (Large Files)
+```bash
+rclone config  # Configure Cloudflare R2
+
+# Upload with optimization
+rclone copy large-video.mp4 r2:my-bucket/ \
+  --s3-upload-cutoff=100M \
+  --s3-chunk-size=100M
+```
+
+## Public Buckets
+
+### Enable Public Access
+1. Dashboard → R2 → Bucket → Settings → Public Access
+2. Add custom domain (recommended) or use r2.dev
+
+**r2.dev (rate-limited):**
+```
+https://pub-<hash>.r2.dev/file.txt
+```
+
+**Custom domain (production):**
+Cloudflare handles DNS/TLS automatically
+
+## CORS Configuration
+
+```bash
+wrangler r2 bucket cors put my-bucket --rules '[
+  {
+    "AllowedOrigins": ["https://example.com"],
+    "AllowedMethods": ["GET", "PUT", "POST"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 3600
+  }
+]'
+```
+
+## Lifecycle Rules
+
+```bash
+wrangler r2 bucket lifecycle put my-bucket --rules '[
+  {
+    "action": {"type": "AbortIncompleteMultipartUpload"},
+    "filter": {},
+    "abortIncompleteMultipartUploadDays": 7
+  },
+  {
+    "action": {"type": "Transition", "storageClass": "InfrequentAccess"},
+    "filter": {"prefix": "archives/"},
+    "daysFromCreation": 90
+  }
+]'
+```
+
+## Event Notifications
+
+```bash
+wrangler r2 bucket notification create my-bucket \
+  --queue=my-queue \
+  --event-type=object-create
+```
+
+Supported events: `object-create`, `object-delete`
+
+## Data Migration
+
+### Sippy (Incremental)
+```bash
+wrangler r2 bucket sippy enable my-bucket \
+  --provider=aws \
+  --bucket=source-bucket \
+  --region=us-east-1 \
+  --access-key-id=$AWS_KEY \
+  --secret-access-key=$AWS_SECRET
+```
+
+Objects migrate on first request.
+
+### Super Slurper (Bulk)
+Use dashboard for one-time complete migration from AWS, GCS, Azure.
+
+## Best Practices
+
+### Performance
+- Use Cloudflare Cache with custom domains
+- Multipart uploads for files >100MB
+- Rclone for batch operations
+- Location hints match user geography
+
+### Security
+- Never commit Access Keys
+- Use environment variables
+- Bucket-scoped tokens for least privilege
+- Presigned URLs for temporary access
+- Enable Cloudflare Access for protection
+
+### Cost Optimization
+- Infrequent Access storage for archives (30+ days)
+- Lifecycle rules to auto-transition/delete
+- Larger multipart chunks = fewer Class A operations
+- Monitor usage via dashboard
+
+### Naming
+- Bucket names: lowercase, hyphens, 3-63 chars
+- Avoid sequential prefixes (use hashed for performance)
+- No dots in bucket names if using custom domains with TLS
+
+## Limits
+
+- Buckets per account: 1,000
+- Object size: 5TB max
+- Lifecycle rules: 1,000 per bucket
+- Event notification rules: 100 per bucket
+- r2.dev rate limit: 1,000 req/min (use custom domains)
+
+## Troubleshooting
+
+**401 Unauthorized:**
+- Verify Access Keys
+- Check endpoint URL includes account ID
+- Ensure region is "auto"
+
+**403 Forbidden:**
+- Check bucket permissions
+- Verify CORS configuration
+- Confirm bucket exists
+
+**Presigned URLs not working:**
+- Verify CORS configuration
+- Check URL expiry time
+- Ensure origin matches CORS rules
+
+## Resources
+
+- Docs: https://developers.cloudflare.com/r2/
+- Wrangler: https://developers.cloudflare.com/r2/reference/wrangler-commands/
+- S3 Compatibility: https://developers.cloudflare.com/r2/api/s3/api/
+- Workers API: https://developers.cloudflare.com/r2/api/workers/