memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/browser-rendering/patterns.md

@@ -0,0 +1,93 @@
+# Browser Rendering Patterns
+
+## Basic Worker
+
+```typescript
+import puppeteer from '@cloudflare/puppeteer'
+
+export default {
+  async fetch(request, env) {
+    const browser = await puppeteer.launch(env.MYBROWSER)
+    try {
+      const page = await browser.newPage()
+      await page.goto('https://example.com')
+      return new Response(await page.content())
+    } finally {
+      await browser.close() // ALWAYS in finally
+    }
+  },
+}
+```
+
+## Session Reuse
+
+Keep sessions alive for performance:
+
+```typescript
+let sessionId = await env.SESSION_KV.get('browser-session')
+if (sessionId) {
+  browser = await puppeteer.connect(env.MYBROWSER, sessionId)
+} else {
+  browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 })
+  await env.SESSION_KV.put('browser-session', browser.sessionId(), { expirationTtl: 600 })
+}
+// Don't close browser to keep session alive
+```
+
+## Common Operations
+
+| Task         | Code                                                                  |
+| ------------ | --------------------------------------------------------------------- |
+| Screenshot   | `await page.screenshot({ type: "png", fullPage: true })`              |
+| PDF          | `await page.pdf({ format: "A4", printBackground: true })`             |
+| Extract data | `await page.evaluate(() => document.querySelector('h1').textContent)` |
+| Fill form    | `await page.type('#input', 'value'); await page.click('button')`      |
+| Wait nav     | `await Promise.all([page.waitForNavigation(), page.click('a')])`      |
+
+## Parallel Scraping
+
+```typescript
+const pages = await Promise.all(urls.map(() => browser.newPage()))
+await Promise.all(pages.map((p, i) => p.goto(urls[i])))
+const titles = await Promise.all(pages.map((p) => p.title()))
+```
+
+## Playwright Selectors
+
+```typescript
+import { launch } from '@cloudflare/playwright'
+const browser = await launch(env.MYBROWSER)
+await page.getByRole('button', { name: 'Sign in' }).click()
+await page.getByLabel('Email').fill('user@example.com')
+await page.getByTestId('submit-button').click()
+```
+
+## Incognito Contexts
+
+Isolated sessions without multiple browsers:
+
+```typescript
+const ctx1 = await browser.createIncognitoBrowserContext()
+const ctx2 = await browser.createIncognitoBrowserContext()
+// Each has isolated cookies/storage
+```
+
+## Quota Check
+
+```typescript
+const limits = await puppeteer.limits(env.MYBROWSER)
+if (limits.remaining < 60000) return new Response('Quota low', { status: 429 })
+```
+
+## Error Handling
+
+```typescript
+try {
+  await page.goto(url, { timeout: 30000, waitUntil: 'networkidle0' })
+} catch (e) {
+  if (e.message.includes('timeout')) return new Response('Timeout', { status: 504 })
+  if (e.message.includes('Session limit')) return new Response('Too many sessions', { status: 429 })
+} finally {
+  if (browser) await browser.close()
+}
+```

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

@@ -0,0 +1,111 @@
+# C3 (create-cloudflare)
+
+Official CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment.
+
+## Quick Start
+
+```bash
+# Interactive (recommended for first-time)
+npm create cloudflare@latest my-app
+
+# Worker (API/WebSocket/Cron)
+npm create cloudflare@latest my-api -- --type=hello-world --ts
+
+# Pages (static/SSG/full-stack)
+npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages
+```
+
+## Platform Decision Tree
+
+```
+What are you building?
+
+├─ API / WebSocket / Cron / Email handler
+│   └─ Workers (default) - no --platform flag needed
+│       npm create cloudflare@latest my-api -- --type=hello-world
+
+├─ Static site / SSG / Documentation
+│   └─ Pages - requires --platform=pages
+│       npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages
+
+├─ Full-stack app (Next.js/Remix/SvelteKit)
+│   ├─ Need Durable Objects, Queues, or Workers-only features?
+│   │   └─ Workers (default)
+│   └─ Otherwise use Pages for git integration and branch previews
+│       └─ Add --platform=pages
+
+└─ Convert existing project
+    └─ npm create cloudflare@latest . -- --type=pre-existing --existing-script=./src/worker.ts
+```
+
+**Critical:** Pages projects require `--platform=pages` flag. Without it, C3 defaults to Workers.
+
+## Interactive Flow
+
+When run without flags, C3 prompts in this order:
+
+1. **Project name** - Directory to create (defaults to current dir with `.`)
+2. **Application type** - `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template`
+3. **Platform** - `workers` (default) or `pages` (for web apps only)
+4. **Framework** - If web-app: `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, etc.
+5. **TypeScript** - `yes` (recommended) or `no`
+6. **Git** - Initialize repository? `yes` or `no`
+7. **Deploy** - Deploy now? `yes` or `no` (requires `wrangler login`)
+
+## Installation Methods
+
+```bash
+# NPM
+npm create cloudflare@latest
+
+# Yarn
+yarn create cloudflare
+
+# PNPM
+pnpm create cloudflare@latest
+```
+
+## In This Reference
+
+| File                 | Purpose                          | Use When                            |
+| -------------------- | -------------------------------- | ----------------------------------- |
+| **api.md**           | Complete CLI flag reference      | Scripting, CI/CD, advanced usage    |
+| **configuration.md** | Generated files, bindings, types | Understanding output, customization |
+| **patterns.md**      | Workflows, CI/CD, monorepos      | Real-world integration              |
+| **gotchas.md**       | Troubleshooting failures         | Deployment blocked, errors          |
+
+## Reading Order
+
+| Task                       | Read                     |
+| -------------------------- | ------------------------ |
+| Create first project       | README only              |
+| Set up CI/CD               | README → api → patterns  |
+| Debug failed deploy        | gotchas                  |
+| Understand generated files | configuration            |
+| Full CLI reference         | api                      |
+| Create custom template     | patterns → configuration |
+| Convert existing project   | README → patterns        |
+
+## Post-Creation
+
+```bash
+cd my-app
+
+# Local dev with hot reload
+npm run dev
+
+# Generate TypeScript types for bindings
+npm run cf-typegen
+
+# Deploy to Cloudflare
+npm run deploy
+```
+
+## See Also
+
+- **workers/README.md** - Workers runtime, bindings, APIs
+- **workers-ai/README.md** - AI/ML models
+- **pages/README.md** - Pages-specific features
+- **wrangler/README.md** - Wrangler CLI beyond initial setup
+- **d1/README.md** - SQLite database
+- **r2/README.md** - Object storage

package/skills/cloudflare/references/c3/api.md

@@ -0,0 +1,71 @@
+# C3 CLI Reference
+
+## Invocation
+
+```bash
+npm create cloudflare@latest [name] [-- flags]  # NPM requires --
+yarn create cloudflare [name] [flags]
+pnpm create cloudflare@latest [name] [-- flags]
+```
+
+## Core Flags
+
+| Flag               | Values                                                                                        | Description                               |
+| ------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `--type`           | `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template`                           | Application type                          |
+| `--platform`       | `workers` (default), `pages`                                                                  | Target platform                           |
+| `--framework`      | `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, `qwik`, `vue`, `angular`, `hono` | Web framework (requires `--type=web-app`) |
+| `--lang`           | `ts`, `js`, `python`                                                                          | Language (for `--type=hello-world`)       |
+| `--ts` / `--no-ts` | -                                                                                             | TypeScript for web apps                   |
+
+## Deployment Flags
+
+| Flag                       | Description                                           |
+| -------------------------- | ----------------------------------------------------- |
+| `--deploy` / `--no-deploy` | Deploy immediately (prompts interactive, skips in CI) |
+| `--git` / `--no-git`       | Initialize git (default: yes)                         |
+| `--open`                   | Open browser after deploy                             |
+
+## Advanced Flags
+
+| Flag                                | Description                                      |
+| ----------------------------------- | ------------------------------------------------ |
+| `--template=user/repo`              | GitHub template or local path                    |
+| `--existing-script=./src/worker.ts` | Existing script (requires `--type=pre-existing`) |
+| `--category=ai\|database\|realtime` | Demo filter (requires `--type=demo`)             |
+| `--experimental`                    | Enable experimental features                     |
+| `--wrangler-defaults`               | Skip wrangler prompts                            |
+
+## Environment Variables
+
+```bash
+CLOUDFLARE_API_TOKEN=xxx    # For deployment
+CLOUDFLARE_ACCOUNT_ID=xxx   # Account ID
+CF_TELEMETRY_DISABLED=1     # Disable telemetry
+```
+
+## Exit Codes
+
+`0` success, `1` user abort, `2` error
+
+## Examples
+
+```bash
+# TypeScript Worker
+npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --no-deploy
+
+# Next.js on Pages
+npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts
+
+# Astro blog
+npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --ts --deploy
+
+# CI: non-interactive
+npm create cloudflare@latest my-app -- --type=web-app --framework=next --ts --no-git --no-deploy
+
+# GitHub template
+npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi
+
+# Convert existing project
+npm create cloudflare@latest . -- --type=pre-existing --existing-script=./build/worker.js
+```

package/skills/cloudflare/references/c3/configuration.md

@@ -0,0 +1,85 @@
+# C3 Generated Configuration
+
+## Output Structure
+
+```
+my-app/
+├── src/index.ts          # Worker entry point
+├── wrangler.jsonc        # Cloudflare config
+├── package.json          # Scripts
+├── tsconfig.json
+└── .gitignore
+```
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json",
+  "name": "my-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-27",
+}
+```
+
+## Binding Placeholders
+
+C3 generates **placeholder IDs** that must be replaced before deploy:
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "MY_KV", "id": "placeholder_kv_id" }],
+  "d1_databases": [{ "binding": "DB", "database_id": "00000000-..." }],
+}
+```
+
+**Replace with real IDs:**
+
+```bash
+npx wrangler kv namespace create MY_KV   # Returns real ID
+npx wrangler d1 create my-database       # Returns real database_id
+```
+
+**Deployment error if not replaced:**
+
+```
+Error: Invalid KV namespace ID "placeholder_kv_id"
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "cf-typegen": "wrangler types"
+  }
+}
+```
+
+## Type Generation
+
+Run after adding bindings:
+
+```bash
+npm run cf-typegen
+```
+
+Generates `.wrangler/types/runtime.d.ts`:
+
+```typescript
+interface Env {
+  MY_KV: KVNamespace
+  DB: D1Database
+}
+```
+
+## Post-Creation Checklist
+
+1. Review `wrangler.jsonc` - check name, compatibility_date
+2. Replace placeholder binding IDs with real resource IDs
+3. Run `npm run cf-typegen`
+4. Test: `npm run dev`
+5. Deploy: `npm run deploy`
+6. Add secrets: `npx wrangler secret put SECRET_NAME`

package/skills/cloudflare/references/c3/gotchas.md

@@ -0,0 +1,97 @@
+# C3 Troubleshooting
+
+## Deployment Issues
+
+### Placeholder IDs
+
+**Error:** "Invalid namespace ID"  
+**Fix:** Replace placeholders in wrangler.jsonc with real IDs:
+
+```bash
+npx wrangler kv namespace create MY_KV  # Get real ID
+```
+
+### Authentication
+
+**Error:** "Not authenticated"  
+**Fix:** `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`
+
+### Name Conflict
+
+**Error:** "Worker already exists"  
+**Fix:** Change `name` in wrangler.jsonc
+
+## Platform Selection
+
+| Need                             | Platform           |
+| -------------------------------- | ------------------ |
+| Git integration, branch previews | `--platform=pages` |
+| Durable Objects, D1, Queues      | Workers (default)  |
+
+Wrong platform? Recreate with correct `--platform` flag.
+
+## TypeScript Issues
+
+**"Cannot find name 'KVNamespace'"**
+
+```bash
+npm run cf-typegen  # Regenerate types
+# Restart TS server in editor
+```
+
+**Missing types after config change:** Re-run `npm run cf-typegen`
+
+## Package Manager
+
+**Multiple lockfiles causing issues:**
+
+```bash
+rm pnpm-lock.yaml  # If using npm
+rm package-lock.json  # If using pnpm
+```
+
+## CI/CD
+
+**CI hangs on prompts:**
+
+```bash
+npm create cloudflare@latest my-app -- \
+  --type=hello-world --lang=ts --no-git --no-deploy
+```
+
+**Auth in CI:**
+
+```yaml
+env:
+  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+## Framework-Specific
+
+| Framework | Issue                  | Fix                              |
+| --------- | ---------------------- | -------------------------------- |
+| Next.js   | create-next-app failed | `npm cache clean --force`, retry |
+| Astro     | Adapter missing        | Install `@astrojs/cloudflare`    |
+| Remix     | Module errors          | Update `@remix-run/cloudflare*`  |
+
+## Compatibility Date
+
+**"Feature X requires compatibility_date >= ..."**  
+**Fix:** Update `compatibility_date` in wrangler.jsonc to today's date
+
+## Node.js Version
+
+**"Node.js version not supported"**  
+**Fix:** Install Node.js 18+ (`nvm install 20`)
+
+## Quick Reference
+
+| Error                   | Cause               | Fix                             |
+| ----------------------- | ------------------- | ------------------------------- |
+| Invalid namespace ID    | Placeholder binding | Create resource, update config  |
+| Not authenticated       | No login            | `npx wrangler login`            |
+| Cannot find KVNamespace | Missing types       | `npm run cf-typegen`            |
+| Worker already exists   | Name conflict       | Change `name`                   |
+| CI hangs                | Missing flags       | Add --type, --lang, --no-deploy |
+| Template not found      | Bad name            | Check cloudflare/templates      |

package/skills/cloudflare/references/c3/patterns.md

@@ -0,0 +1,84 @@
+# C3 Usage Patterns
+
+## Quick Workflows
+
+```bash
+# TypeScript API Worker
+npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --deploy
+
+# Next.js on Pages
+npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts --deploy
+
+# Astro static site
+npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --platform=pages --ts
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+- name: Deploy
+  run: npm run deploy
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+**Non-interactive requires:**
+
+```bash
+--type=<value>       # Required
+--no-git             # Recommended (CI already in git)
+--no-deploy          # Deploy separately with secrets
+--framework=<value>  # For web-app
+--ts / --no-ts       # Required
+```
+
+## Monorepo
+
+C3 detects workspace config (`package.json` workspaces or `pnpm-workspace.yaml`).
+
+```bash
+cd packages/
+npm create cloudflare@latest my-worker -- --type=hello-world --lang=ts --no-deploy
+```
+
+## Custom Templates
+
+```bash
+# GitHub repo
+npm create cloudflare@latest -- --template=username/repo
+npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi
+
+# Local path
+npm create cloudflare@latest my-app -- --template=../my-template
+```
+
+**Template requires `c3.config.json`:**
+
+```json
+{
+  "name": "my-template",
+  "category": "hello-world",
+  "copies": [{ "path": "src/" }, { "path": "wrangler.jsonc" }],
+  "transforms": [{ "path": "package.json", "jsonc": { "name": "{{projectName}}" } }]
+}
+```
+
+## Existing Projects
+
+```bash
+# Add Cloudflare to existing Worker
+npm create cloudflare@latest . -- --type=pre-existing --existing-script=./dist/index.js
+
+# Add to existing framework app
+npm create cloudflare@latest . -- --type=web-app --framework=next --platform=pages --ts
+```
+
+## Post-Creation Checklist
+
+1. Review `wrangler.jsonc` - set `compatibility_date`, verify `name`
+2. Create bindings: `wrangler kv namespace create`, `wrangler d1 create`, `wrangler r2 bucket create`
+3. Generate types: `npm run cf-typegen`
+4. Test: `npm run dev`
+5. Deploy: `npm run deploy`
+6. Set secrets: `wrangler secret put SECRET_NAME`

package/skills/cloudflare/references/cache-reserve/README.md

@@ -0,0 +1,150 @@
+# Cloudflare Cache Reserve
+
+**Persistent cache storage built on R2 for long-term content retention**
+
+## Smart Shield Integration
+
+Cache Reserve is part of **Smart Shield**, Cloudflare's comprehensive security and performance suite:
+
+- **Smart Shield Advanced tier**: Includes 2TB Cache Reserve storage
+- **Standalone purchase**: Available separately if not using Smart Shield
+- **Migration**: Existing standalone customers can migrate to Smart Shield bundles
+
+**Decision**: Already on Smart Shield Advanced? Cache Reserve is included. Otherwise evaluate standalone purchase vs Smart Shield upgrade.
+
+## Overview
+
+Cache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.
+
+## Core Concepts
+
+### What is Cache Reserve?
+
+- **Persistent storage layer**: Built on R2, sits above tiered cache hierarchy
+- **Long-term retention**: 30-day default retention, extended on each access
+- **Automatic operation**: Works seamlessly with existing CDN, no code changes required
+- **Origin shielding**: Dramatically reduces origin egress by serving cached content longer
+- **Usage-based pricing**: Pay only for storage + read/write operations
+
+### Cache Hierarchy
+
+```
+Visitor Request
+    ↓
+Lower-Tier Cache (closest to visitor)
+    ↓ (on miss)
+Upper-Tier Cache (closest to origin)
+    ↓ (on miss)
+Cache Reserve (R2 persistent storage)
+    ↓ (on miss)
+Origin Server
+```
+
+### How It Works
+
+1. **On cache miss**: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously
+2. **On edge eviction**: Content may be evicted from edge cache but remains in Cache Reserve
+3. **On subsequent request**: If edge cache misses but Cache Reserve hits → content restored to edge caches
+4. **Retention**: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)
+
+## When to Use Cache Reserve
+
+```
+Need persistent caching?
+├─ High origin egress costs → Cache Reserve ✓
+├─ Long-tail content (archives, media libraries) → Cache Reserve ✓
+├─ Already using Smart Shield Advanced → Included! ✓
+├─ Video streaming with seeking (range requests) → ✗ Not supported
+├─ Dynamic/personalized content → ✗ Use edge cache only
+├─ Need per-request cache control from Workers → ✗ Use R2 directly
+└─ Frequently updated content (< 10hr lifetime) → ✗ Not eligible
+```
+
+## Asset Eligibility
+
+Cache Reserve only stores assets meeting **ALL** criteria:
+
+- Cacheable per Cloudflare's standard rules
+- Minimum 10-hour TTL (36000 seconds)
+- `Content-Length` header present
+- Original files only (not transformed images)
+
+### Eligibility Checklist
+
+Use this checklist to verify if an asset is eligible:
+
+- [ ] Zone has Cache Reserve enabled
+- [ ] Zone has Tiered Cache enabled (required)
+- [ ] Asset TTL ≥ 10 hours (36,000 seconds)
+- [ ] `Content-Length` header present on origin response
+- [ ] No `Set-Cookie` header (or uses private directive)
+- [ ] `Vary` header is NOT `*` (can be `Accept-Encoding`)
+- [ ] Not an image transformation variant (original images OK)
+- [ ] Not a range request (no HTTP 206 support)
+- [ ] Not O2O (Orange-to-Orange) proxied request
+
+**All boxes must be checked for Cache Reserve eligibility.**
+
+### Not Eligible
+
+- Assets with TTL < 10 hours
+- Responses without `Content-Length` header
+- Image transformation variants (original images are eligible)
+- Responses with `Set-Cookie` headers
+- Responses with `Vary: *` header
+- Assets from R2 public buckets on same zone
+- O2O (Orange-to-Orange) setup requests
+- **Range requests** (video seeking, partial content downloads)
+
+## Quick Start
+
+```bash
+# Enable via Dashboard
+https://dash.cloudflare.com/caching/cache-reserve
+# Click "Enable Storage Sync" or "Purchase" button
+```
+
+**Prerequisites:**
+
+- Paid Cache Reserve plan or Smart Shield Advanced required
+- Tiered Cache required for optimal performance
+
+## Essential Commands
+
+```bash
+# Check Cache Reserve status
+curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# Enable Cache Reserve
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+
+# Check asset cache status
+curl -I https://example.com/asset.jpg | grep -i cache
+```
+
+## In This Reference
+
+| Task                                                  | Files                                                     |
+| ----------------------------------------------------- | --------------------------------------------------------- |
+| Evaluate if Cache Reserve fits your use case          | README.md (this file)                                     |
+| Enable Cache Reserve for your zone                    | README.md + [configuration.md](./configuration.md)        |
+| Use with Workers (understand limitations)             | [api.md](./api.md)                                        |
+| Setup via SDKs or IaC (TypeScript, Python, Terraform) | [configuration.md](./configuration.md)                    |
+| Optimize costs and debug issues                       | [patterns.md](./patterns.md) + [gotchas.md](./gotchas.md) |
+| Understand eligibility and troubleshoot               | [gotchas.md](./gotchas.md) → [patterns.md](./patterns.md) |
+
+**Files:**
+
+- [configuration.md](./configuration.md) - Setup, API, SDKs, and Cache Rules
+- [api.md](./api.md) - Purging, monitoring, Workers integration
+- [patterns.md](./patterns.md) - Best practices, cost optimization, debugging
+- [gotchas.md](./gotchas.md) - Common issues, limitations, troubleshooting
+
+## See Also
+
+- [r2](../r2/) - Cache Reserve built on R2 storage
+- [workers](../workers/) - Workers integration with Cache API