update skills

.agents/skills/cloudflare-deploy/references/web-analytics/gotchas.md

@@ -0,0 +1,82 @@
+# Web Analytics Gotchas
+
+## Critical Issues
+
+### SPA Navigation Not Tracked
+
+**Symptom:** Only initial pageload counted  
+**Fix:** Add `spa: true`:
+```html
+<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
+```
+
+### CSP Blocking Beacon
+
+**Symptom:** Console error "Refused to load script"  
+**Fix:** Allow both domains:
+```
+script-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+### Hash-Based Routing Unsupported
+
+**Symptom:** `#/path` URLs not tracked  
+**Fix:** Migrate to History API (`BrowserRouter`, not `HashRouter`). No workaround for hash routing.
+
+### No Data Appearing
+
+**Causes & Fixes:**
+1. **Delay** - Wait 5-15 minutes
+2. **Wrong token** - Verify matches dashboard exactly
+3. **Script blocked** - Check DevTools Network tab for beacon.min.js
+4. **Domain mismatch** - Dashboard site must match actual URL
+
+### Auto-Injection Fails
+
+**Cause:** `Cache-Control: no-transform` header  
+**Fix:** Remove `no-transform` or install beacon manually
+
+### Duplicate Pageviews
+
+**Cause:** Multiple beacon scripts  
+**Fix:** Keep only one beacon per page
+
+## Configuration Issues
+
+| Issue | Fix |
+|-------|-----|
+| 10-site limit reached | Delete old sites or proxy through CF (unlimited) |
+| Token not recognized | Use exact alphanumeric token from dashboard |
+
+## Framework-Specific
+
+### Next.js Hydration Warning
+
+```tsx
+<script suppressHydrationWarning ... />
+```
+
+### Gatsby Window Undefined
+
+Use `gatsby-browser.js` to load client-side only.
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Non-proxied sites | 10 |
+| Proxied sites | Unlimited |
+| Data retention | 6 months |
+| Ingestion delay | 5-10 min |
+| API access | None (dashboard only) |
+
+## When NOT to Use Web Analytics
+
+Use alternatives if you need:
+- Custom event tracking
+- Real-time data
+- User-level tracking
+- Conversion funnels
+- Data export/API access
+
+**Web Analytics excels at:** Core Web Vitals, basic traffic, privacy compliance, free unlimited pageviews.