memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,253 @@
+# Troubleshooting & Gotchas
+
+## Critical Rules
+
+### ❌ Skipping Server-Side Validation
+
+**Problem:** Client-only validation is easily bypassed.
+
+**Solution:** Always validate on server.
+
+```javascript
+// CORRECT - Server validates token
+app.post('/submit', async (req, res) => {
+  const token = req.body['cf-turnstile-response']
+  const validation = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+    method: 'POST',
+    body: JSON.stringify({ secret: SECRET, response: token }),
+  }).then((r) => r.json())
+
+  if (!validation.success) return res.status(403).json({ error: 'CAPTCHA failed' })
+})
+```
+
+### ❌ Exposing Secret Key
+
+**Problem:** Secret key leaked in client-side code.
+
+**Solution:** Server-side validation only. Never send secret to client.
+
+### ❌ Reusing Tokens (Single-Use Rule)
+
+**Problem:** Tokens are single-use. Revalidation fails with `timeout-or-duplicate`.
+
+**Solution:** Generate new token for each submission. Reset widget on error.
+
+```javascript
+if (!response.ok) window.turnstile.reset(widgetId)
+```
+
+### ❌ Not Handling Token Expiry
+
+**Problem:** Tokens expire after 5 minutes.
+
+**Solution:** Handle expiry callback or use auto-refresh.
+
+```javascript
+window.turnstile.render('#container', {
+  sitekey: 'YOUR_SITE_KEY',
+  'refresh-expired': 'auto', // or 'manual' with expired-callback
+  'expired-callback': () => window.turnstile.reset(widgetId),
+})
+```
+
+## Common Errors
+
+| Error                      | Cause                                             | Solution                                                          |
+| -------------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
+| **Widget not rendering**   | Incorrect sitekey, CSP blocking, file:// protocol | Check sitekey, add CSP for challenges.cloudflare.com, use http:// |
+| **timeout-or-duplicate**   | Token expired (>5min) or reused                   | Generate fresh token, don't cache >5min                           |
+| **invalid-input-secret**   | Wrong secret key                                  | Verify secret from dashboard, check env vars                      |
+| **missing-input-response** | Token not sent                                    | Check form field name is 'cf-turnstile-response'                  |
+
+## Framework Gotchas
+
+### React: Widget Re-mounting
+
+**Problem:** Widget re-renders on state change, losing token.
+
+**Solution:** Control lifecycle with useRef.
+
+```tsx
+function TurnstileWidget({ onToken }) {
+  const containerRef = useRef(null)
+  const widgetIdRef = useRef(null)
+
+  useEffect(() => {
+    if (containerRef.current && !widgetIdRef.current) {
+      widgetIdRef.current = window.turnstile.render(containerRef.current, {
+        sitekey: 'YOUR_SITE_KEY',
+        callback: onToken,
+      })
+    }
+    return () => {
+      if (widgetIdRef.current) {
+        window.turnstile.remove(widgetIdRef.current)
+        widgetIdRef.current = null
+      }
+    }
+  }, [])
+
+  return <div ref={containerRef} />
+}
+```
+
+### React StrictMode: Double Render
+
+**Problem:** Widget renders twice in dev due to StrictMode.
+
+**Solution:** Use cleanup function.
+
+```tsx
+useEffect(() => {
+  const widgetId = window.turnstile.render('#container', { sitekey })
+  return () => window.turnstile.remove(widgetId)
+}, [])
+```
+
+### Next.js: SSR Hydration
+
+**Problem:** `window.turnstile` undefined during SSR.
+
+**Solution:** Use `'use client'` or dynamic import with `ssr: false`.
+
+```tsx
+'use client'
+export default function Turnstile() {
+  /* component */
+}
+```
+
+### SPA: Navigation Without Cleanup
+
+**Problem:** Navigating leaves orphaned widgets.
+
+**Solution:** Remove widget in cleanup.
+
+```javascript
+// Vue
+onBeforeUnmount(() => window.turnstile.remove(widgetId))
+
+// React
+useEffect(() => () => window.turnstile.remove(widgetId), [])
+```
+
+## Network & Security
+
+### CSP Blocking
+
+**Problem:** Content Security Policy blocks script/iframe.
+
+**Solution:** Add CSP directives.
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="script-src 'self' https://challenges.cloudflare.com; 
+               frame-src https://challenges.cloudflare.com;"
+/>
+```
+
+### IP Address Forwarding
+
+**Problem:** Server receives proxy IP instead of client IP.
+
+**Solution:** Use correct header.
+
+```javascript
+// Cloudflare Workers
+const ip = request.headers.get('CF-Connecting-IP')
+
+// Behind proxy
+const ip = request.headers.get('X-Forwarded-For')?.split(',')[0]
+```
+
+### CORS (Siteverify)
+
+**Problem:** CORS error calling siteverify from browser.
+
+**Solution:** Never call siteverify client-side. Call your backend, backend calls siteverify.
+
+## Limits & Constraints
+
+| Limit          | Value                                  | Impact                       |
+| -------------- | -------------------------------------- | ---------------------------- |
+| Token validity | 5 minutes                              | Must regenerate after expiry |
+| Token use      | Single-use                             | Cannot revalidate same token |
+| Widget size    | 300x65px (normal), 130x120px (compact) | Plan layout                  |
+
+## Debugging
+
+### Console Logging
+
+```javascript
+window.turnstile.render('#container', {
+  sitekey: 'YOUR_SITE_KEY',
+  callback: (token) => console.log('✓ Token:', token),
+  'error-callback': (code) => console.error('✗ Error:', code),
+  'expired-callback': () => console.warn('⏱ Expired'),
+  'timeout-callback': () => console.warn('⏱ Timeout'),
+})
+```
+
+### Check Token State
+
+```javascript
+const token = window.turnstile.getResponse(widgetId)
+console.log('Token:', token || 'NOT READY')
+console.log('Expired:', window.turnstile.isExpired(widgetId))
+```
+
+### Test Keys (Use First)
+
+Always develop with test keys before production:
+
+- Site: `1x00000000000000000000AA`
+- Secret: `1x0000000000000000000000000000000AA`
+
+### Network Tab
+
+- Verify `api.js` loads (200 OK)
+- Check siteverify request/response
+- Look for 4xx/5xx errors
+
+## Misconfigurations
+
+### Wrong Key Pairing
+
+**Problem:** Site key from one widget, secret from another.
+
+**Solution:** Verify site key and secret are from same widget in dashboard.
+
+### Test Keys in Production
+
+**Problem:** Using test keys in production.
+
+**Solution:** Environment-based keys.
+
+```javascript
+const SITE_KEY =
+  process.env.NODE_ENV === 'production'
+    ? process.env.TURNSTILE_SITE_KEY
+    : '1x00000000000000000000AA'
+```
+
+### Missing Environment Variables
+
+**Problem:** Secret undefined on server.
+
+**Solution:** Check .env and verify loading.
+
+```bash
+# .env
+TURNSTILE_SECRET=your_secret_here
+
+# Verify
+console.log('Secret loaded:', !!process.env.TURNSTILE_SECRET);
+```
+
+## Reference
+
+- [Turnstile Docs](https://developers.cloudflare.com/turnstile/)
+- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
+- [Error Codes](https://developers.cloudflare.com/turnstile/troubleshooting/)

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

@@ -0,0 +1,195 @@
+# Common Patterns
+
+## Form Integration
+
+### Basic Form (Implicit Rendering)
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+  </head>
+  <body>
+    <form action="/submit" method="POST">
+      <input type="email" name="email" required />
+      <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
+      <button type="submit">Submit</button>
+    </form>
+  </body>
+</html>
+```
+
+### Controlled Form (Explicit Rendering)
+
+```javascript
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
+<script>
+let widgetId = window.turnstile.render('#container', {
+  sitekey: 'YOUR_SITE_KEY',
+  callback: (token) => console.log('Token:', token)
+});
+
+form.addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const token = window.turnstile.getResponse(widgetId);
+  if (!token) return;
+
+  const response = await fetch('/submit', {
+    method: 'POST',
+    body: JSON.stringify({ 'cf-turnstile-response': token })
+  });
+
+  if (!response.ok) window.turnstile.reset(widgetId);
+});
+</script>
+```
+
+## Framework Patterns
+
+### React
+
+```tsx
+import { useState } from 'react'
+import Turnstile from '@marsidev/react-turnstile'
+
+export default function Form() {
+  const [token, setToken] = useState<string | null>(null)
+
+  return (
+    <form
+      onSubmit={async (e) => {
+        e.preventDefault()
+        if (!token) return
+        await fetch('/api/submit', {
+          method: 'POST',
+          body: JSON.stringify({ 'cf-turnstile-response': token }),
+        })
+      }}
+    >
+      <Turnstile siteKey="YOUR_SITE_KEY" onSuccess={setToken} />
+      <button disabled={!token}>Submit</button>
+    </form>
+  )
+}
+```
+
+### Vue / Svelte
+
+```vue
+<!-- Vue: npm install vue-turnstile -->
+<VueTurnstile :site-key="SITE_KEY" @success="token = $event" />
+
+<!-- Svelte: npm install svelte-turnstile -->
+<Turnstile siteKey={SITE_KEY} on:turnstile-callback={(e) => token = e.detail.token} />
+```
+
+## Server Validation
+
+### Cloudflare Workers
+
+```typescript
+interface Env {
+  TURNSTILE_SECRET: string
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method !== 'POST') {
+      return new Response('Method not allowed', { status: 405 })
+    }
+
+    const formData = await request.formData()
+    const token = formData.get('cf-turnstile-response')
+
+    if (!token) {
+      return new Response('Missing token', { status: 400 })
+    }
+
+    // Validate token
+    const ip = request.headers.get('CF-Connecting-IP')
+    const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        secret: env.TURNSTILE_SECRET,
+        response: token,
+        remoteip: ip,
+      }),
+    })
+
+    const validation = await result.json()
+
+    if (!validation.success) {
+      return new Response('CAPTCHA validation failed', { status: 403 })
+    }
+
+    // Process form...
+    return new Response('Success')
+  },
+}
+```
+
+### Pages Functions
+
+```typescript
+// functions/submit.ts - same pattern as Workers, use ctx.env and ctx.request
+export const onRequestPost: PagesFunction<{ TURNSTILE_SECRET: string }> = async (ctx) => {
+  const token = (await ctx.request.formData()).get('cf-turnstile-response')
+  // Validate with ctx.env.TURNSTILE_SECRET (same as Workers pattern above)
+}
+```
+
+## Advanced Patterns
+
+### Pre-Clearance (Invisible)
+
+```html
+<div id="turnstile-precheck"></div>
+<form id="protected-form" style="display: none;">
+  <button type="submit">Submit</button>
+</form>
+
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
+<script>
+  let cachedToken = null
+
+  window.onload = () => {
+    window.turnstile.render('#turnstile-precheck', {
+      sitekey: 'YOUR_SITE_KEY',
+      size: 'invisible',
+      callback: (token) => {
+        cachedToken = token
+        document.getElementById('protected-form').style.display = 'block'
+      },
+    })
+  }
+</script>
+```
+
+### Token Refresh on Expiry
+
+```javascript
+let widgetId = window.turnstile.render('#container', {
+  sitekey: 'YOUR_SITE_KEY',
+  'refresh-expired': 'manual',
+  'expired-callback': () => {
+    console.log('Token expired, refreshing...')
+    window.turnstile.reset(widgetId)
+  },
+})
+```
+
+## Testing
+
+### Environment-Based Keys
+
+```javascript
+const SITE_KEY =
+  process.env.NODE_ENV === 'production' ? 'YOUR_PRODUCTION_SITE_KEY' : '1x00000000000000000000AA' // Always passes
+
+const SECRET_KEY =
+  process.env.NODE_ENV === 'production'
+    ? process.env.TURNSTILE_SECRET
+    : '1x0000000000000000000000000000000AA'
+```

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

@@ -0,0 +1,133 @@
+# Cloudflare Vectorize
+
+Globally distributed vector database for AI applications. Store and query vector embeddings for semantic search, recommendations, RAG, and classification.
+
+**Status:** Generally Available (GA) | **Last Updated:** 2026-01-27
+
+## Quick Start
+
+```typescript
+// 1. Create index
+// npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
+
+// 2. Configure binding (wrangler.jsonc)
+// { "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }] }
+
+// 3. Query vectors
+const matches = await env.VECTORIZE.query(queryVector, { topK: 5 })
+```
+
+## Key Features
+
+- **10M vectors per index** (V2)
+- Dimensions up to 1536 (32-bit float)
+- Three distance metrics: cosine, euclidean, dot-product
+- Metadata filtering (up to 10 indexes)
+- Namespace support (50K namespaces paid, 1K free)
+- Seamless Workers AI integration
+- Global distribution
+
+## Reading Order
+
+| Task               | Files to Read           |
+| ------------------ | ----------------------- |
+| New to Vectorize   | README only             |
+| Implement feature  | README + api + patterns |
+| Setup/configure    | README + configuration  |
+| Debug issues       | gotchas                 |
+| Integrate with AI  | README + patterns       |
+| RAG implementation | README + patterns       |
+
+## File Guide
+
+- **README.md** (this file): Overview, quick decisions
+- **api.md**: Runtime API, types, operations (query/insert/upsert)
+- **configuration.md**: Setup, CLI, metadata indexes
+- **patterns.md**: RAG, Workers AI, OpenAI, LangChain, multi-tenant
+- **gotchas.md**: Limits, pitfalls, troubleshooting
+
+## Distance Metric Selection
+
+Choose based on your use case:
+
+```
+What are you building?
+├─ Text/semantic search → cosine (most common)
+├─ Image similarity → euclidean
+├─ Recommendation system → dot-product
+└─ Pre-normalized vectors → dot-product
+```
+
+| Metric        | Best For                             | Score Interpretation              |
+| ------------- | ------------------------------------ | --------------------------------- |
+| `cosine`      | Text embeddings, semantic similarity | Higher = closer (1.0 = identical) |
+| `euclidean`   | Absolute distance, spatial data      | Lower = closer (0.0 = identical)  |
+| `dot-product` | Recommendations, normalized vectors  | Higher = closer                   |
+
+**Note:** Index configuration is immutable. Cannot change dimensions or metric after creation.
+
+## Multi-Tenancy Strategy
+
+```
+How many tenants?
+├─ < 50K tenants → Use namespaces (recommended)
+│   ├─ Fastest (filter before vector search)
+│   └─ Strict isolation
+├─ > 50K tenants → Use metadata filtering
+│   ├─ Slower (post-filter after vector search)
+│   └─ Requires metadata index
+└─ Per-tenant indexes → Only if compliance mandated
+    └─ 50K index limit per account (paid plan)
+```
+
+## Common Workflows
+
+### Semantic Search
+
+```typescript
+// 1. Generate embedding
+const result = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [query] })
+
+// 2. Query Vectorize
+const matches = await env.VECTORIZE.query(result.data[0], {
+  topK: 5,
+  returnMetadata: 'indexed',
+})
+```
+
+### RAG Pattern
+
+```typescript
+// 1. Generate query embedding
+const embedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [query] })
+
+// 2. Search Vectorize
+const matches = await env.VECTORIZE.query(embedding.data[0], { topK: 5 })
+
+// 3. Fetch full documents from R2/D1/KV
+const docs = await Promise.all(
+  matches.matches.map((m) => env.R2.get(m.metadata.key).then((obj) => obj?.text()))
+)
+
+// 4. Generate LLM response with context
+const answer = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
+  prompt: `Context: ${docs.join('\n\n')}\n\nQuestion: ${query}\n\nAnswer:`,
+})
+```
+
+## Critical Gotchas
+
+See `gotchas.md` for details. Most important:
+
+1. **Async mutations**: Inserts take 5-10s to be queryable
+2. **500 batch limit**: Workers API enforces 500 vectors per call (undocumented)
+3. **Metadata truncation**: `"indexed"` returns first 64 bytes only
+4. **topK with metadata**: Max 20 (not 100) when using returnValues or returnMetadata: "all"
+5. **Metadata indexes first**: Must create before inserting vectors
+
+## Resources
+
+- [Official Docs](https://developers.cloudflare.com/vectorize/)
+- [Client API Reference](https://developers.cloudflare.com/vectorize/reference/client-api/)
+- [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/#text-embeddings)
+- [Discord: #vectorize](https://discord.cloudflare.com)

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

@@ -0,0 +1,89 @@
+# Vectorize API Reference
+
+## Types
+
+```typescript
+interface VectorizeVector {
+  id: string // Max 64 bytes
+  values: number[] // Must match index dimensions
+  namespace?: string // Optional partition (max 64 bytes)
+  metadata?: Record<string, any> // Max 10 KiB
+}
+```
+
+## Query
+
+```typescript
+const matches = await env.VECTORIZE.query(queryVector, {
+  topK: 10, // Max 100 (or 20 with returnValues/returnMetadata:"all")
+  returnMetadata: 'indexed', // "none" | "indexed" | "all"
+  returnValues: false,
+  namespace: 'tenant-123',
+  filter: { category: 'docs' },
+})
+// matches.matches[0] = { id, score, metadata? }
+```
+
+**returnMetadata:** `"none"` (fastest) → `"indexed"` (recommended) → `"all"` (topK max 20)
+
+**queryById (V2 only):** Search using existing vector as query.
+
+```typescript
+await env.VECTORIZE.queryById('doc-123', { topK: 5 })
+```
+
+## Insert/Upsert
+
+```typescript
+// Insert: ignores duplicates (keeps first)
+await env.VECTORIZE.insert([{ id, values, metadata }])
+
+// Upsert: overwrites duplicates (keeps last)
+await env.VECTORIZE.upsert([{ id, values, metadata }])
+```
+
+**Max 500 vectors per call.** Queryable after 5-10 seconds.
+
+## Other Operations
+
+```typescript
+// Get by IDs
+const vectors = await env.VECTORIZE.getByIds(['id1', 'id2'])
+
+// Delete (max 1000 IDs per call)
+await env.VECTORIZE.deleteByIds(['id1', 'id2'])
+
+// Index info
+const info = await env.VECTORIZE.describe()
+// { dimensions, metric, vectorCount }
+```
+
+## Filtering
+
+Requires metadata index. Filter operators:
+
+| Operator                     | Example                          |
+| ---------------------------- | -------------------------------- |
+| `$eq` (implicit)             | `{ category: "docs" }`           |
+| `$ne`                        | `{ status: { $ne: "deleted" } }` |
+| `$in` / `$nin`               | `{ tag: { $in: ["sale"] } }`     |
+| `$lt`, `$lte`, `$gt`, `$gte` | `{ price: { $lt: 100 } }`        |
+
+**Constraints:** Max 2048 bytes, no dots/`$` in keys, values: string/number/boolean/null.
+
+## Performance
+
+| Configuration               | topK Limit | Speed   |
+| --------------------------- | ---------- | ------- |
+| No metadata                 | 100        | Fastest |
+| `returnMetadata: "indexed"` | 100        | Fast    |
+| `returnMetadata: "all"`     | 20         | Slower  |
+| `returnValues: true`        | 20         | Slower  |
+
+**Batch operations:** Always batch (500/call) for optimal throughput.
+
+```typescript
+for (let i = 0; i < vectors.length; i += 500) {
+  await env.VECTORIZE.upsert(vectors.slice(i, i + 500))
+}
+```