memory-journal-mcp 7.7.1 → 8.0.1

package/skills/cloudflare/references/web-analytics/README.md

@@ -0,0 +1,149 @@
+# Cloudflare Web Analytics
+
+Privacy-first web analytics providing Core Web Vitals, traffic metrics, and user insights without compromising visitor privacy.
+
+## Overview
+
+Cloudflare Web Analytics provides:
+
+- **Core Web Vitals** - LCP, FID, CLS, INP, TTFB monitoring
+- **Page views & visits** - Traffic patterns without cookies
+- **Referrers & paths** - Traffic sources and popular pages
+- **Device & browser data** - User agent breakdown
+- **Geographic data** - Country-level visitor distribution
+- **Privacy-first** - No cookies, fingerprinting, or PII collection
+- **Free** - No cost, unlimited pageviews
+
+**Important:** Web Analytics is **dashboard-only**. No API exists for programmatic data access.
+
+## Quick Start Decision Tree
+
+```
+Is your site proxied through Cloudflare?
+├─ YES → Use automatic injection (configuration.md)
+│   ├─ Enable auto-injection in dashboard
+│   └─ No code changes needed (unless Cache-Control: no-transform)
+│
+└─ NO → Use manual beacon integration (integration.md)
+    ├─ Add JS snippet to HTML
+    ├─ Use spa: true for React/Vue/Next.js
+    └─ Configure CSP if needed
+```
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Setup for proxied vs non-proxied sites
+2. **[integration.md](integration.md)** - Framework-specific beacon integration (React, Next.js, Vue, Nuxt, etc.)
+3. **[patterns.md](patterns.md)** - Common use cases (performance monitoring, GDPR consent, multi-site tracking)
+4. **[gotchas.md](gotchas.md)** - Troubleshooting (SPA tracking, CSP issues, hash routing limitations)
+
+## When to Use Each File
+
+- **Setting up for first time?** → Start with configuration.md
+- **Using React/Next.js/Vue/Nuxt?** → Go to integration.md for framework code
+- **Need GDPR consent loading?** → See patterns.md
+- **Beacon not loading or no data?** → Check gotchas.md
+- **SPA not tracking navigation?** → See integration.md for `spa: true` config
+
+## Key Concepts
+
+### Proxied vs Non-Proxied Sites
+
+| Type            | Description                           | Beacon Injection    | Limit        |
+| --------------- | ------------------------------------- | ------------------- | ------------ |
+| **Proxied**     | DNS through Cloudflare (orange cloud) | Automatic or manual | Unlimited    |
+| **Non-proxied** | External hosting, manual beacon       | Manual only         | 10 sites max |
+
+### SPA Mode
+
+**Critical for modern frameworks:**
+
+```json
+{ "token": "YOUR_TOKEN", "spa": true }
+```
+
+Without `spa: true`, client-side navigation (React Router, Vue Router, Next.js routing) will NOT be tracked. Only initial page loads will register.
+
+### CSP Requirements
+
+If using Content Security Policy, allow both domains:
+
+```
+script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+## Features
+
+### Core Web Vitals Debugging
+
+- **LCP (Largest Contentful Paint)** - Identifies slow-loading hero images/elements
+- **FID (First Input Delay)** - Interaction responsiveness (legacy metric)
+- **INP (Interaction to Next Paint)** - Modern interaction responsiveness metric
+- **CLS (Cumulative Layout Shift)** - Visual stability issues
+- **TTFB (Time to First Byte)** - Server response performance
+
+Dashboard shows top 5 problematic elements with CSS selectors for debugging.
+
+### Traffic Filters
+
+- **Bot filtering** - Exclude automated traffic from metrics
+- **Date ranges** - Custom time period analysis
+- **Geographic** - Country-level filtering
+- **Device type** - Desktop, mobile, tablet breakdown
+- **Browser/OS** - User agent filtering
+
+### Rules (Advanced - Plan-dependent)
+
+Create custom tracking rules for advanced configurations:
+
+**Sample Rate Rules:**
+
+- Reduce data collection percentage for high-traffic sites
+- Example: Track only 50% of visitors to reduce volume
+
+**Path-Based Rules:**
+
+- Different behavior per route
+- Example: Exclude `/admin/*` or `/internal/*` from tracking
+
+**Host-Based Rules:**
+
+- Multi-domain configurations
+- Example: Separate tracking for staging vs production subdomains
+
+**Availability:** Rules feature depends on your Cloudflare plan. Check dashboard under Web Analytics → Rules to see if available. Free plans may have limited or no access.
+
+## Plan Limits
+
+| Feature           | Free           | Notes                  |
+| ----------------- | -------------- | ---------------------- |
+| Proxied sites     | Unlimited      | DNS through Cloudflare |
+| Non-proxied sites | 10             | External hosting       |
+| Pageviews         | Unlimited      | No volume limits       |
+| Data retention    | 6 months       | Rolling window         |
+| Rules             | Plan-dependent | Check dashboard        |
+
+## Privacy & Compliance
+
+- **No cookies** - Zero client-side storage
+- **No fingerprinting** - No tracking across sites
+- **No PII** - IP addresses not stored
+- **GDPR-friendly** - Minimal data collection
+- **CCPA-compliant** - No personal data sale
+
+**EU opt-out:** Dashboard option to exclude EU visitor data entirely.
+
+## Limitations
+
+- **Dashboard-only** - No API for programmatic access
+- **No real-time** - 5-10 minute data delay
+- **No custom events** - Automatic pageview/navigation tracking only
+- **History API only** - Hash-based routing (`#/path`) not supported
+- **No session replay** - Metrics only, no user recordings
+- **No form tracking** - Page navigation tracking only
+
+## See Also
+
+- [Cloudflare Web Analytics Docs](https://developers.cloudflare.com/analytics/web-analytics/)
+- [Core Web Vitals Guide](https://web.dev/vitals/)
+- [GraphQL Analytics API Reference](../graphql-api/) - Query server-side analytics (HTTP, Workers, DNS, Firewall, etc.) via GraphQL

package/skills/cloudflare/references/web-analytics/configuration.md

@@ -0,0 +1,81 @@
+# Configuration
+
+## Setup Methods
+
+### Proxied Sites (Automatic)
+
+Dashboard → Web Analytics → Add site → Select hostname → Done
+
+| Injection Option           | Description                            |
+| -------------------------- | -------------------------------------- |
+| Enable                     | Auto-inject for all visitors (default) |
+| Enable, excluding EU       | No injection for EU (GDPR)             |
+| Enable with manual snippet | You add beacon manually                |
+| Disable                    | Pause tracking                         |
+
+**Fails if response has:** `Cache-Control: public, no-transform`
+
+**CSP required:**
+
+```
+script-src https://static.cloudflareinsights.com https://cloudflareinsights.com;
+```
+
+### Non-Proxied Sites (Manual)
+
+Dashboard → Web Analytics → Add site → Enter hostname → Copy snippet
+
+```html
+<script
+  defer
+  src="https://static.cloudflareinsights.com/beacon.min.js"
+  data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'
+></script>
+```
+
+**Limits:** 10 non-proxied sites per account
+
+## SPA Mode
+
+**Enable `spa: true` for:** React Router, Next.js, Vue Router, Nuxt, SvelteKit, Angular
+
+**Keep `spa: false` for:** Traditional multi-page apps, static sites, WordPress
+
+**Hash routing (`#/path`) NOT supported** - use History API routing.
+
+## Token Management
+
+- Found in: Dashboard → Web Analytics → Manage site
+- **Not secrets** - domain-locked, safe to expose in HTML
+- Each site gets unique token
+
+## Environment Config
+
+```typescript
+// Only load in production
+if (process.env.NODE_ENV === 'production') {
+  // Load beacon
+}
+```
+
+Or use environment-specific tokens via env vars.
+
+## Verify Installation
+
+1. DevTools Network → filter `cloudflareinsights` → see `beacon.min.js` + data request
+2. No CSP/CORS errors in console
+3. Dashboard shows pageviews after 5-10 min delay
+
+## Rules (Plan-dependent)
+
+Configure in dashboard for:
+
+- **Sample rate** - reduce collection % for high-traffic
+- **Path-based** - different behavior per route
+- **Host-based** - separate tracking per domain
+
+## Data Retention
+
+- 6 months rolling window
+- 1-hour bucket granularity
+- No raw export, dashboard only

package/skills/cloudflare/references/web-analytics/gotchas.md

@@ -0,0 +1,86 @@
+# 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.

package/skills/cloudflare/references/web-analytics/integration.md

@@ -0,0 +1,63 @@
+# Framework Integration
+
+**Web Analytics is dashboard-only** - no programmatic API. This covers beacon integration.
+
+## Basic HTML
+
+```html
+<script
+  defer
+  src="https://static.cloudflareinsights.com/beacon.min.js"
+  data-cf-beacon='{"token": "YOUR_TOKEN", "spa": true}'
+></script>
+```
+
+Place before closing `</body>` tag.
+
+## Framework Examples
+
+| Framework          | Location                   | Notes                                      |
+| ------------------ | -------------------------- | ------------------------------------------ |
+| React/Vite         | `public/index.html`        | Add `spa: true`                            |
+| Next.js App Router | `app/layout.tsx`           | Use `<Script strategy="afterInteractive">` |
+| Next.js Pages      | `pages/_document.tsx`      | Use `<Script>`                             |
+| Nuxt 3             | `app.vue` with `useHead()` | Or use plugin                              |
+| Vue 3/Vite         | `index.html`               | Add `spa: true`                            |
+| Gatsby             | `gatsby-browser.js`        | `onClientEntry` hook                       |
+| SvelteKit          | `src/app.html`             | Before `</body>`                           |
+| Astro              | Layout component           | Before `</body>`                           |
+| Angular            | `src/index.html`           | Add `spa: true`                            |
+| Docusaurus         | `docusaurus.config.js`     | In `scripts` array                         |
+
+## Configuration
+
+```json
+{
+  "token": "YOUR_TOKEN",
+  "spa": true
+}
+```
+
+**Use `spa: true` for:** React Router, Vue Router, Next.js, Nuxt, Gatsby, SvelteKit, Angular
+
+**Use `spa: false` for:** Traditional server-rendered (PHP, Django, Rails, WordPress)
+
+## CSP Headers
+
+```
+script-src 'self' https://static.cloudflareinsights.com;
+connect-src 'self' https://cloudflareinsights.com;
+```
+
+## GDPR Consent
+
+```typescript
+// Load conditionally based on consent
+if (localStorage.getItem('analytics-consent') === 'true') {
+  const script = document.createElement('script')
+  script.src = 'https://static.cloudflareinsights.com/beacon.min.js'
+  script.defer = true
+  script.setAttribute('data-cf-beacon', '{"token": "YOUR_TOKEN", "spa": true}')
+  document.body.appendChild(script)
+}
+```

package/skills/cloudflare/references/web-analytics/patterns.md

@@ -0,0 +1,98 @@
+# Web Analytics Patterns
+
+## Core Web Vitals Debugging
+
+Dashboard → Core Web Vitals → Click metric → Debug View shows top 5 problematic elements.
+
+### LCP Fixes
+
+```html
+<!-- Priority hints -->
+<img src="hero.jpg" loading="eager" fetchpriority="high" />
+<link rel="preload" as="image" href="/hero.jpg" fetchpriority="high" />
+```
+
+### CLS Fixes
+
+```css
+/* Reserve space */
+.ad-container {
+  min-height: 250px;
+}
+img {
+  width: 400px;
+  height: 300px;
+} /* Explicit dimensions */
+```
+
+### INP Fixes
+
+```typescript
+// Debounce expensive operations
+const handleInput = debounce(search, 300)
+
+// Yield to main thread
+await task()
+await new Promise((r) => setTimeout(r, 0))
+await task2()
+
+// Move to Web Worker for heavy computation
+```
+
+| Metric | Good   | Poor   |
+| ------ | ------ | ------ |
+| LCP    | ≤2.5s  | >4s    |
+| INP    | ≤200ms | >500ms |
+| CLS    | ≤0.1   | >0.25  |
+
+## GDPR Consent
+
+```typescript
+// Load beacon only after consent
+const consent = localStorage.getItem('analytics-consent')
+if (consent === 'accepted') {
+  const script = document.createElement('script')
+  script.src = 'https://static.cloudflareinsights.com/beacon.min.js'
+  script.setAttribute('data-cf-beacon', '{"token": "TOKEN", "spa": true}')
+  document.body.appendChild(script)
+}
+```
+
+Alternative: Dashboard → "Enable, excluding visitor data in the EU"
+
+## SPA Navigation
+
+```html
+<!-- REQUIRED for React/Vue/etc routing -->
+<script data-cf-beacon='{"token": "TOKEN", "spa": true}' ...></script>
+```
+
+Without `spa: true`: only initial pageload tracked.
+
+## Staging/Production Separation
+
+```typescript
+// Use env-specific tokens
+const token = process.env.NEXT_PUBLIC_CF_ANALYTICS_TOKEN
+// .env.production: production token
+// .env.staging: staging token (or empty to disable)
+```
+
+## Bot Filtering
+
+Dashboard → Filters → "Exclude Bot Traffic"
+
+Filters: Search crawlers, monitoring services, known bots.  
+Not filtered: Headless browsers (Playwright/Puppeteer).
+
+## Ad-Blocker Impact
+
+~25-40% of users may block `cloudflareinsights.com`. No official workaround.
+Dashboard shows minimum baseline; use server logs for complete picture.
+
+## Limitations
+
+- No UTM parameter tracking
+- No webhooks/alerts/API
+- No custom beacon domains
+- Max 10 non-proxied sites

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

@@ -0,0 +1,85 @@
+# Workerd Runtime
+
+V8-based JS/Wasm runtime powering Cloudflare Workers. Use as app server, dev tool, or HTTP proxy.
+
+## ⚠️ IMPORTANT SECURITY NOTICE
+
+**workerd is NOT a hardened sandbox.** Do not run untrusted code. It's designed for deploying YOUR code locally/self-hosted, not multi-tenant SaaS. Cloudflare production adds security layers not present in open-source workerd.
+
+## Decision Tree: When to Use What
+
+**95% of users:** Use Wrangler
+
+- Local development: `wrangler dev` (uses workerd internally)
+- Deployment: `wrangler deploy` (deploys to Cloudflare)
+- Types: `wrangler types` (generates TypeScript types)
+
+**Use raw workerd directly only if:**
+
+- Self-hosting Workers runtime in production
+- Embedding runtime in C++ application
+- Custom tooling/testing infrastructure
+- Debugging workerd-specific behavior
+
+**Never use workerd for:**
+
+- Running untrusted/user-submitted code
+- Multi-tenant isolation (not hardened)
+- Production without additional security layers
+
+## Key Features
+
+- **Standards-based**: Fetch API, Web Crypto, Streams, WebSocket
+- **Nanoservices**: Service bindings with local call performance
+- **Capability security**: Explicit bindings prevent SSRF
+- **Backwards compatible**: Version = max compat date supported
+
+## Architecture
+
+```
+Config (workerd.capnp)
+├── Services (workers/endpoints)
+├── Sockets (HTTP/HTTPS listeners)
+└── Extensions (global capabilities)
+```
+
+## Quick Start
+
+```bash
+workerd serve config.capnp
+workerd compile config.capnp myConfig -o binary
+workerd test config.capnp
+```
+
+## Platform Support & Beta Status
+
+| Platform        | Status       | Notes                     |
+| --------------- | ------------ | ------------------------- |
+| Linux (x64)     | Stable       | Primary platform          |
+| macOS (x64/ARM) | Stable       | Full support              |
+| Windows         | Beta         | Use WSL2 for best results |
+| Linux (ARM64)   | Experimental | Limited testing           |
+
+workerd is in **active development**. Breaking changes possible. Pin versions in production.
+
+## Core Concepts
+
+- **Service**: Named endpoint (worker/network/disk/external)
+- **Binding**: Capability-based resource access (KV/DO/R2/services)
+- **Compatibility date**: Feature gate (always set!)
+- **Modules**: ES modules (recommended) or service worker syntax
+
+## Reading Order (Progressive Disclosure)
+
+**Start here:**
+
+1. This README (overview, decision tree)
+2. [patterns.md](./patterns.md) - Common workflows, framework examples
+
+**When you need details:** 3. [configuration.md](./configuration.md) - Config format, services, bindings 4. [api.md](./api.md) - Runtime APIs, TypeScript types 5. [gotchas.md](./gotchas.md) - Common errors, debugging
+
+## Related References
+
+- [workers](../workers/) - Workers runtime API documentation
+- [miniflare](../miniflare/) - Testing tool built on workerd
+- [wrangler](../wrangler/) - CLI that uses workerd for local dev