CastQuest · SMSDAO · Jan 22, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
diff --git a/DOCS_VALIDATION_REPORT.md b/DOCS_VALIDATION_REPORT.md
diff --git a/docs-site/agents/index.mdx b/docs-site/agents/index.mdx
diff --git a/docs-site/agents/setup.mdx b/docs-site/agents/setup.mdx
diff --git a/docs-site/frames/setup.mdx b/docs-site/frames/setup.mdx
@@ -0,0 +1,353 @@
+---
+title: "Frames Setup & Configuration"
+section: "frames"
+slug: "setup"
+tags: ["frames", "farcaster", "setup"]
+weight: 1
+navOrder: 1
+---
+
+# Frames Setup & Configuration
+
+> CASTQUEST V3 — Farcaster Frames Integration Guide
+
+## Overview
+
+Frames are interactive Farcaster integrations that allow users to interact with CASTQUEST directly from their Farcaster feed. The frames feature is built into the web application.
+
+**Code Path:** `apps/web/app/frames/` (part of web application)
+
+## Architecture
+
+Frames are server-rendered HTML with specific meta tags that Farcaster clients render as interactive cards. CASTQUEST frames support:
+
+- **Quest Frames**: Create and complete quests
+- **Mint Frames**: Mint NFTs and tokens
+- **Marketplace Frames**: Browse and purchase items
+- **Profile Frames**: Display user profiles and stats
+
+### Technology
+
+- **Framework**: Next.js API routes
+- **Rendering**: Server-side rendering (SSR)
+- **Validation**: Farcaster signature verification
+- **Storage**: PostgreSQL for frame state
+- **Integration**: Farcaster Hub API
+
+## Prerequisites
+
+- Web application setup (see Web App Setup)
+- Farcaster account with developer access
+- Farcaster Hub access (self-hosted or Neynar)
+
+## Environment Variables
+
+### Required
+
+- **`FARCASTER_APP_FID`**: Farcaster application FID (Farcaster ID)
+  - Example: `12345`
+  - Obtain from: https://www.farcaster.xyz/
+  - Used for: Frame authentication
+
+- **`FARCASTER_APP_MNEMONIC`**: App mnemonic for signing
+  - Format: 24-word BIP39 mnemonic
+  - CRITICAL: Keep secret, never commit
+  - Used for: Signing frame responses
+
+### Optional
+
+- **`FARCASTER_HUB_URL`**: Farcaster Hub URL
+  - Default: `https://hub.farcaster.xyz`
+  - Alternative: Self-hosted hub or Neynar
+
+- **`FARCASTER_API_KEY`**: API key for Farcaster services
+  - Required if using hosted services
+  - Obtain from service provider
+
+### Example Configuration
+
+```bash
+# In .env.local or .env.production
+
+# Farcaster Configuration
+FARCASTER_APP_FID=12345
+FARCASTER_APP_MNEMONIC="word1 word2 word3 ... word24"
+FARCASTER_HUB_URL=https://hub.farcaster.xyz
+FARCASTER_API_KEY=fc_api_key_here
+```
+
+## Setup Steps
+
+### 1. Register Farcaster App
+
+1. Go to https://www.farcaster.xyz/
+2. Create new application
+3. Note your FID (Farcaster ID)
+4. Generate app mnemonic
+5. Save credentials securely
+
+### 2. Configure Environment
+
+Add Farcaster credentials to environment:
+
+```bash
+# Development
+cp .env.local.example .env.local
+# Edit .env.local and add Farcaster variables
+
+# Production
+# Add variables to hosting platform (Vercel, K8s secrets)
+```
+
+### 3. Implement Frame Routes
+
+Frame routes are in `apps/web/app/frames/[type]/route.ts`:
+
+```typescript
+// Example: apps/web/app/frames/quest/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(req: NextRequest) {
+  // Render frame HTML with meta tags
+  return new NextResponse(frameHtml, {
+    headers: { 'Content-Type': 'text/html' }
+  });
+}
+
+export async function POST(req: NextRequest) {
+  // Handle frame button click
+  const body = await req.json();
+  // Verify Farcaster signature
+  // Process action
+  // Return updated frame
+}
+```
+
+### 4. Test Frames
+
+Test using Farcaster Frame Validator:
+- https://warpcast.com/~/developers/frames
+
+## Build & Development
+
+Frames are part of the web application:
+
+```bash
+# Development with hot reload
+pnpm --filter @castquest/web dev
+
+# Production build
+pnpm --filter @castquest/web build
+
+# Start production server
+pnpm --filter @castquest/web start
+```
+
+## Deployment
+
+Frames are deployed as part of the web application:
+
+### Frame URL Structure
+
+- Development: `http://localhost:3000/frames/*`
+- Production: `https://castquest.io/frames/*`
+
+### Deployment Steps
+
+1. **Deploy Web App**: Frames deploy with main web application
+   ```bash
+   # Build and deploy
+   pnpm --filter @castquest/web build
+   vercel --prod
+   ```
+
+2. **Verify Frame URLs**: Ensure frame routes are accessible
+   ```bash
+   curl https://castquest.io/frames/quest/1
+   ```
+
+3. **Test in Farcaster**: Post frame URL to verify rendering
+   - Use Warpcast or other Farcaster client
+   - Verify interactive elements work
+   - Test all button actions
+
+4. **Monitor Performance**: Track frame metrics
+   - View counts
+   - Interaction rates
+   - Error rates
+   - Load times
+
+### CDN Configuration
+
+Optimize frame delivery:
+- Enable CDN caching for static assets
+- Set appropriate cache headers
+- Use image optimization
+- Compress responses
+
+### Frame Registry
+
+Register frames in Farcaster:
+1. Submit frame URL to Farcaster registry
+2. Verify ownership
+3. Monitor indexing status
+
+## Security
+
+### Signature Verification
+
+Always verify Farcaster signatures on frame actions:
+
+```typescript
+import { verifyFrameSignature } from '@/lib/farcaster';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+
+  const isValid = await verifyFrameSignature(body);
+  if (!isValid) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+
+  // Process valid request
+}
+```
+
+### Mnemonic Security
+
+- Store mnemonic in secrets manager (AWS Secrets Manager, Vault)
+- Never log or expose mnemonic
+- Use environment variables, not hardcoded values
+- Rotate if compromised
+
+### Input Sanitization
+
+Sanitize all user inputs in frames:
+
+```typescript
+import { sanitize } from '@/lib/sanitize';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+
+  // Sanitize inputs
+  const sanitizedInput = sanitize(body.inputText);
+
+  // Validate
+  if (!isValid(sanitizedInput)) {
+    return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
+  }
+}
+```
+
+### CORS Configuration
+
+Configure CORS for frame endpoints:
+
+```typescript
+export async function GET(req: NextRequest) {
+  return new NextResponse(html, {
+    headers: {
+      'Content-Type': 'text/html',
+      'Access-Control-Allow-Origin': 'https://warpcast.com',
+      'Access-Control-Allow-Methods': 'GET, POST',
+    }
+  });
+}
+```
+
+### Security Best Practices
+
+- **Always verify signatures**: Never trust unsigned frame actions
+- **Validate all inputs**: Sanitize and validate user inputs
+- **Rate limit endpoints**: Prevent abuse and spam
+- **Log security events**: Monitor for suspicious activity
+- **Use HTTPS**: Always use secure connections
+- **Keep secrets secure**: Never expose mnemonics or keys
+- **Monitor frame abuse**: Track and block malicious frames
+
+## Monitoring
+
+### Frame Analytics
+
+Track frame interactions:
+- View counts
+- Button clicks
+- Conversion rates
+- Error rates
+
+### Error Tracking
+
+Monitor frame errors:
+- Invalid signatures
+- API failures
+- Rendering errors
+- Timeout issues
+
+### Performance
+
+Optimize frame performance:
+- Cache rendered frames (Redis)
+- Optimize images (Next.js Image)
+- Minimize response size
+- Use CDN for assets
+
+## Frame Types
+
+### Quest Frames
+
+Create and complete quests via frames:
+- Path: `/frames/quest/[id]`
+- Actions: View, start, complete quest
+- Data: Quest details, progress, rewards
+
+### Mint Frames
+
+Mint NFTs and tokens:
+- Path: `/frames/mint/[id]`
+- Actions: View, mint, verify
+- Data: Mint details, pricing, eligibility
+
+### Marketplace Frames
+
+Browse marketplace items:
+- Path: `/frames/marketplace/[id]`
+- Actions: View, buy, offer
+- Data: Item details, price, seller
+
+### Profile Frames
+
+Display user profiles:
+- Path: `/frames/profile/[address]`
+- Actions: View, follow, tip
+- Data: Profile info, stats, tokens
+
+## Troubleshooting
+
+**"Frame not rendering"**
+- Check meta tags format
+- Verify frame URL is accessible
+- Test with Frame Validator
+- Check Content-Type header
+
+**"Invalid signature"**
+- Verify FARCASTER_APP_MNEMONIC is correct
+- Check signature verification logic
+- Ensure Hub URL is accessible
+
+**"Hub connection failed"**
+- Verify FARCASTER_HUB_URL is correct
+- Check network connectivity
+- Try alternative Hub (Neynar)
+
+## Next Steps
+
+- [Frame Types](/frames/frame-types) - Supported frame types
+- [Frame Templates](/frames/frame-templates) - Frame templates
+- [Farcaster Integration](/frames/farcaster-integration) - Deep dive
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/frames
+- **Discord**: https://discord.gg/castquest