update skills

.agents/skills/cloudflare-deploy/references/tail-workers/configuration.md

@@ -0,0 +1,176 @@
+# Tail Workers Configuration
+
+## Setup Steps
+
+### 1. Create Tail Worker
+
+Create a Worker with a `tail()` handler:
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    // Process events from producer Worker
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: "POST",
+        body: JSON.stringify(events),
+      })
+    );
+  }
+};
+```
+
+### 2. Configure Producer Worker
+
+In producer's `wrangler.jsonc`:
+
+```jsonc
+{
+  "name": "my-producer-worker",
+  "tail_consumers": [
+    {
+      "service": "my-tail-worker"
+    }
+  ]
+}
+```
+
+### 3. Deploy Both Workers
+
+```bash
+# Deploy Tail Worker first
+cd tail-worker
+wrangler deploy
+
+# Then deploy producer Worker
+cd ../producer-worker
+wrangler deploy
+```
+
+## Wrangler Configuration
+
+### Single Tail Consumer
+
+```jsonc
+{
+  "name": "producer-worker",
+  "tail_consumers": [
+    {
+      "service": "logging-tail-worker"
+    }
+  ]
+}
+```
+
+### Multiple Tail Consumers
+
+```jsonc
+{
+  "name": "producer-worker",
+  "tail_consumers": [
+    {
+      "service": "logging-tail-worker"
+    },
+    {
+      "service": "metrics-tail-worker"
+    }
+  ]
+}
+```
+
+**Note:** Each consumer receives ALL events independently.
+
+### Remove Tail Consumer
+
+```jsonc
+{
+  "tail_consumers": []
+}
+```
+
+Then redeploy producer Worker.
+
+## Environment Variables
+
+Tail Workers use same binding syntax as regular Workers:
+
+```jsonc
+{
+  "name": "my-tail-worker",
+  "vars": {
+    "LOG_ENDPOINT": "https://logs.example.com/ingest"
+  },
+  "kv_namespaces": [
+    {
+      "binding": "LOGS_KV",
+      "id": "abc123..."
+    }
+  ]
+}
+```
+
+## Testing & Development
+
+### Local Testing
+
+**Tail Workers cannot be fully tested with `wrangler dev`.** Deploy to staging environment for testing.
+
+### Testing Strategy
+
+1. Deploy producer Worker to staging
+2. Deploy Tail Worker to staging
+3. Configure `tail_consumers` in producer
+4. Trigger producer Worker requests
+5. Verify Tail Worker receives events (check destination logs/storage)
+
+### Wrangler Tail Command
+
+```bash
+# Stream logs to terminal (NOT Tail Workers)
+wrangler tail my-producer-worker
+```
+
+**This is different from Tail Workers:**
+- `wrangler tail` streams logs to your terminal
+- Tail Workers are Workers that process events programmatically
+
+## Deployment Checklist
+
+- [ ] Tail Worker has `tail()` handler
+- [ ] Tail Worker deployed before producer
+- [ ] Producer's `wrangler.jsonc` has correct `tail_consumers`
+- [ ] Environment variables configured
+- [ ] Tested with staging environment
+- [ ] Monitoring configured for Tail Worker itself
+
+## Limits
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Max tail consumers per producer | 10 | Each receives all events independently |
+| Events batch size | Up to 100 events per invocation | Larger batches split across invocations |
+| Tail Worker CPU time | Same as regular Workers | 10ms (free), 30ms (paid), 50ms (paid bundle) |
+| Pricing tier | Workers Paid or Enterprise | Not available on free plan |
+| Request body size | 100 MB max | When sending to external endpoints |
+| Event retention | None | Events not retried if tail handler fails |
+
+## Workers for Platforms
+
+For dynamic dispatch Workers, both dispatch and user Worker events sent to tail consumer:
+
+```jsonc
+{
+  "name": "dispatch-worker",
+  "tail_consumers": [
+    {
+      "service": "platform-tail-worker"
+    }
+  ]
+}
+```
+
+Tail Worker receives TWO `TraceItem` elements per request:
+1. Dynamic dispatch Worker event
+2. User Worker event
+
+See [patterns.md](patterns.md) for handling.