diff --git a/DOCS_VALIDATION_REPORT.md b/DOCS_VALIDATION_REPORT.md
index f18e043..ba221c2 100644
--- a/DOCS_VALIDATION_REPORT.md
+++ b/DOCS_VALIDATION_REPORT.md
@@ -1,504 +1,252 @@
-# CastQuest Documentation Validation Report
+# Documentation Validation Report
-**Generated:** 2026-01-19T09:05:31.224Z
-**Repository:** CastQuest/cast
-**Purpose:** Non-blocking validation and audit of documentation completeness and accuracy
+Generated: 2026-01-20T06:02:25.416Z
----
+This report identifies documentation gaps across the CastQuest repository.
+Each feature should have complete documentation covering:
+- architecture
+- setup
+- environment variables
+- build
+- deployment
+- security
-## Executive Summary
+## Summary
-This report provides a comprehensive audit of the CastQuest monorepo documentation against implemented features and production workflows.
+- ✅ Complete: 0
+- ⚠️ Partial: 3
+- ❌ Incomplete: 6
+- 🚫 Missing: 0
-### Coverage Statistics
+## Feature Details
-- **Total Features Inventoried:** 55
-- **Fully Documented:** 12
-- **Partially Documented:** 17
-- **Missing Documentation:** 26
-- **Documentation Pages Analyzed:** 241
-- **Completeness Issues Found:** 236
-- **Consistency Issues Found:** 0
+### ⚠️ SDK
----
+**Status:** PARTIAL
-## 1. Feature Inventory
+**Code Path:** `packages/sdk/`
-### 1.1 Web Application (apps/web)
+**Docs Path:** `docs-site/sdk/`
-**Web Application (Next.js)**
-- Location: `apps/web`
-- Pages: 15
-- Components: 12
-- Scripts: dev, build, start, lint, typecheck, test
+**Environment Variables:**
+- `CASTQUEST_API_KEY`
+- `CASTQUEST_NETWORK`
-### 1.2 Smart Contracts (packages/contracts)
+**Build Command:** `pnpm --filter @castquest/sdk build`
-**core** (7 contracts)
-- Contracts: CastToken, CodeToken, FramToken, GameToken, MediaToken, QuestToken, UserProfile
+**Test Command:** `pnpm --filter @castquest/sdk test`
-**economy** (4 contracts)
-- Contracts: BuybackRouter, FeeManager, RevenueRouter, SponsorToken
+**Section Coverage:**
-**governance** (4 contracts)
-- Contracts: AIDaoConstitution, AgentRegistry, GovernanceV2, SubDAOFactory
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ⚠️ security: PARTIAL
-**l3** (2 contracts)
-- Contracts: L3Bridge, RollupFactory
-
-**marketplace** (3 contracts)
-- Contracts: AuctionHouse, Marketplace, SponsorMarketplace
-
-**social** (2 contracts)
-- Contracts: FarcasterFrameRegistry, SocialAutomationConfig
-
-### 1.3 SDK Modules (packages/sdk)
-
-- **agents**: module
-- **bridge**: module
-- **code**: module
-- **fram**: module
-- **game**: module
-- **governance**: module
-- **index**: module
-- **l3**: module
-- **marketplace**: module
-- **media**: module
-- **profile**: module
-- **wallet**: module
-
-### 1.4 AI Agents (packages/agents)
-
-- AuctionAgent
-- CreationAgent
-- CurationAgent
-- FrameAgent
-- FraudAgent
-- GameAgent
-- PortfolioAgent
-- PricingAgent
-- SocialAutomationAgent
-- SyncAgent
-- UiAgent
-
-### 1.5 Indexers (packages/indexer)
-
-- buyback-indexer
-- mc-indexer
-- social-indexer
-
-### 1.6 Infrastructure (infra/)
-
-**Docker:**
-- Dockerfile.indexer
-- Dockerfile.web
-
-**Kubernetes:**
-- k8s/production/web-deployment.yaml
-- k8s/staging/web-deployment.yaml
-
-**Terraform:**
-- bootstrap.tf
-- github-actions-role.tf
-- main.tf
-
-**Scripts:**
-- setup-permissions.sh
-- validate-k8s.js
-
-### 1.7 GitHub Workflows (.github/workflows/)
-
-**build**
-- Jobs: push, workflow_dispatch, build-web, build-sdk, build-contracts, build-docs, build-docker
-
-**ci**
-- Jobs: pull_request, push, group, cancel-in-progress, lint-and-test, contracts-test
-
-**deploy**
-- Jobs: workflow_dispatch, id-token, contents, deploy-infra, deploy-web, deploy-contracts, deploy-docs, publish-sdk
-
-
----
-
-## 2. Feature-to-Documentation Mapping
-
-| Feature | Source Directory | Docs Pages | Coverage |
-|---------|------------------|------------|----------|
-| Contract: CastToken | `packages/contracts/core/` | frames/farcaster-integration.mdx, integrations/farcaster.mdx... | **FULL** |
-| Contract: CodeToken | `packages/contracts/core/` | reference/error-codes.mdx | **FULL** |
-| Contract: FramToken | `packages/contracts/core/` | brain-engine/integration-with-frames.mdx, builders/frame-builder.mdx... | **FULL** |
-| Contract: GameToken | `packages/contracts/core/` | NONE | **MISSING** |
-| Contract: MediaToken | `packages/contracts/core/` | NONE | **MISSING** |
-| Contract: QuestToken | `packages/contracts/core/` | builders/quest-builder.mdx, frames/frame-quests.mdx... | **FULL** |
-| Contract: UserProfile | `packages/contracts/core/` | NONE | **MISSING** |
-| Contract: BuybackRouter | `packages/contracts/economy/` | [ROOT]/RELEASE.md | **FULL** |
-| Contract: FeeManager | `packages/contracts/economy/` | [ROOT]/RELEASE.md | **FULL** |
-| Contract: RevenueRouter | `packages/contracts/economy/` | NONE | **MISSING** |
-| Contract: SponsorToken | `packages/contracts/economy/` | [ROOT]/README.md, [ROOT]/CHANGELOG.md... | **FULL** |
-| Contract: AIDaoConstitution | `packages/contracts/governance/` | NONE | **MISSING** |
-| Contract: AgentRegistry | `packages/contracts/governance/` | NONE | **MISSING** |
-| Contract: GovernanceV2 | `packages/contracts/governance/` | [ROOT]/CHANGELOG.md, [ROOT]/RELEASE.md | **FULL** |
-| Contract: SubDAOFactory | `packages/contracts/governance/` | NONE | **MISSING** |
-| Contract: L3Bridge | `packages/contracts/l3/` | [ROOT]/README.md, [ROOT]/CHANGELOG.md... | **FULL** |
-| Contract: RollupFactory | `packages/contracts/l3/` | [ROOT]/README.md, [ROOT]/CHANGELOG.md... | **FULL** |
-| Contract: AuctionHouse | `packages/contracts/marketplace/` | NONE | **MISSING** |
-| Contract: Marketplace | `packages/contracts/marketplace/` | admin-dashboard/alerts.mdx, admin-dashboard/audit-logs.mdx... | **FULL** |
-| Contract: SponsorMarketplace | `packages/contracts/marketplace/` | [ROOT]/RELEASE.md | **FULL** |
-| Contract: FarcasterFrameRegistry | `packages/contracts/social/` | NONE | **MISSING** |
-| Contract: SocialAutomationConfig | `packages/contracts/social/` | NONE | **MISSING** |
-| SDK: agents | `/packages/sdk/agents.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: bridge | `/packages/sdk/bridge.ts` | NONE | **MISSING** |
-| SDK: code | `/packages/sdk/code.ts` | NONE | **MISSING** |
-| SDK: fram | `/packages/sdk/fram.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: game | `/packages/sdk/game.ts` | NONE | **MISSING** |
-| SDK: governance | `/packages/sdk/governance.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: index | `/packages/sdk/index.ts` | sdk/index.mdx | **PARTIAL** |
-| SDK: l3 | `/packages/sdk/l3.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: marketplace | `/packages/sdk/marketplace.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: media | `/packages/sdk/media.ts` | NONE | **MISSING** |
-| SDK: profile | `/packages/sdk/profile.ts` | sdk/admin-sdk.mdx, sdk/auth.mdx... | **PARTIAL** |
-| SDK: wallet | `/packages/sdk/wallet.ts` | NONE | **MISSING** |
-| Agent: AuctionAgent | `/packages/agents/AuctionAgent.ts` | NONE | **MISSING** |
-| Agent: CreationAgent | `/packages/agents/CreationAgent.ts` | NONE | **MISSING** |
-| Agent: CurationAgent | `/packages/agents/CurationAgent.ts` | NONE | **MISSING** |
-| Agent: FrameAgent | `/packages/agents/FrameAgent.ts` | NONE | **MISSING** |
-| Agent: FraudAgent | `/packages/agents/FraudAgent.ts` | NONE | **MISSING** |
-| Agent: GameAgent | `/packages/agents/GameAgent.ts` | NONE | **MISSING** |
-| Agent: PortfolioAgent | `/packages/agents/PortfolioAgent.ts` | NONE | **MISSING** |
-| Agent: PricingAgent | `/packages/agents/PricingAgent.ts` | NONE | **MISSING** |
-| Agent: SocialAutomationAgent | `/packages/agents/SocialAutomationAgent.ts` | NONE | **MISSING** |
-| Agent: SyncAgent | `/packages/agents/SyncAgent.ts` | NONE | **MISSING** |
-| Agent: UiAgent | `/packages/agents/UiAgent.ts` | NONE | **MISSING** |
-| Infra: docker/Dockerfile.indexer | `infra/docker/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: docker/Dockerfile.web | `infra/docker/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: kubernetes/k8s/production/web-deployment.yaml | `infra/kubernetes/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: kubernetes/k8s/staging/web-deployment.yaml | `infra/kubernetes/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: terraform/bootstrap.tf | `infra/terraform/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: terraform/github-actions-role.tf | `infra/terraform/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Infra: terraform/main.tf | `infra/terraform/` | builders/deployment-flows.mdx | **PARTIAL** |
-| Workflow: build | `/.github/workflows/build.yml` | admin-dashboard/alerts.mdx, admin-dashboard/audit-logs.mdx... | **PARTIAL** |
-| Workflow: ci | `/.github/workflows/ci.yml` | fees-and-treasury/buyback-policies.mdx, index.md... | **PARTIAL** |
-| Workflow: deploy | `/.github/workflows/deploy.yml` | builders/deployment-flows.mdx, fees-and-treasury/buyback-policies.mdx... | **PARTIAL** |
-
----
-
-## 3. Documentation Completeness Analysis
-
-Found 236 documentation pages with missing sections:
-
-### admin-dashboard/alerts.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/audit-logs.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/fee-controls.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/index.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/overview-metrics.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/pause-protocol.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/permissions.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/protocol-fees.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/risk-management.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/system-status.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/token-management.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/tvl-and-volume.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### admin-dashboard/user-metrics.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
-
-### agents/alerting-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+### ❌ Agents
-### agents/automation-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Status:** INCOMPLETE
-### agents/backtesting-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Code Path:** `packages/agents/`
-### agents/brain-engine-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Docs Path:** `docs-site/agents/`
-### agents/governance-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Environment Variables:**
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `REPLICATE_API_KEY`
-### agents/index.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Build Command:** `pnpm --filter @castquest/agents build`
-### agents/market-making-agents.mdx
-- **Severity:** HIGH
-- **Missing Sections:** Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Test Command:** `pnpm --filter @castquest/agents test`
+**Section Coverage:**
-_... and 216 more pages with missing sections._
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
----
+### ❌ Indexer
-## 4. Documentation Consistency Issues
+**Status:** INCOMPLETE
-✅ No consistency issues found in documentation.
+**Code Path:** `packages/indexer/`
----
+**Docs Path:** `docs-site/overview/`
-## 5. Production Readiness Assessment
+**Environment Variables:**
+- `DATABASE_URL`
+- `REDIS_URL`
+- `BASE_RPC_URL`
+- `ETHEREUM_RPC_URL`
-### BLOCKER Priority
+**Build Command:** `pnpm --filter @castquest/indexer build`
-✅ **Production Build Steps**: ADEQUATE (8 mentions)
-✅ **CI/CD Pipeline Documentation**: ADEQUATE (31 mentions)
-✅ **Infrastructure Deployment**: ADEQUATE (154 mentions)
+**Test Command:** `pnpm --filter @castquest/indexer test`
-### IMPORTANT Priority
+**Section Coverage:**
-✅ **Secret Management**: ADEQUATE (15 mentions)
-✅ **Monitoring & Alerting**: ADEQUATE (485 mentions)
-✅ **Upgrade/Migration Guide**: ADEQUATE (273 mentions)
-✅ **Disaster Recovery**: ADEQUATE (20 mentions)
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ⚠️ build: PARTIAL
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
-### OPTIONAL Priority
+### ❌ Contracts
-✅ **Performance Tuning**: ADEQUATE (15 mentions)
+**Status:** INCOMPLETE
----
+**Code Path:** `packages/contracts/`
-## 6. Missing Documentation Checklist
+**Docs Path:** `docs-site/protocol/`
-The following documentation pages or sections are recommended:
+**Environment Variables:**
+- `DEPLOYER_PRIVATE_KEY`
+- `BASE_RPC_URL`
+- `BASESCAN_API_KEY`
-### Features Without Documentation
+**Build Command:** `pnpm --filter @castquest/contracts build`
-- [ ] **Contract: GameToken**
- - Source: `packages/contracts/core/`
- - Suggested location: `docs-site/protocol/contract-gametoken.mdx`
+**Test Command:** `pnpm --filter @castquest/contracts test`
-- [ ] **Contract: MediaToken**
- - Source: `packages/contracts/core/`
- - Suggested location: `docs-site/protocol/contract-mediatoken.mdx`
+**Section Coverage:**
-- [ ] **Contract: UserProfile**
- - Source: `packages/contracts/core/`
- - Suggested location: `docs-site/protocol/contract-userprofile.mdx`
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
-- [ ] **Contract: RevenueRouter**
- - Source: `packages/contracts/economy/`
- - Suggested location: `docs-site/protocol/contract-revenuerouter.mdx`
+### ❌ Web App
-- [ ] **Contract: AIDaoConstitution**
- - Source: `packages/contracts/governance/`
- - Suggested location: `docs-site/protocol/contract-aidaoconstitution.mdx`
+**Status:** INCOMPLETE
-- [ ] **Contract: AgentRegistry**
- - Source: `packages/contracts/governance/`
- - Suggested location: `docs-site/protocol/contract-agentregistry.mdx`
+**Code Path:** `apps/web/`
-- [ ] **Contract: SubDAOFactory**
- - Source: `packages/contracts/governance/`
- - Suggested location: `docs-site/protocol/contract-subdaofactory.mdx`
+**Docs Path:** `docs-site/overview/`
-- [ ] **Contract: AuctionHouse**
- - Source: `packages/contracts/marketplace/`
- - Suggested location: `docs-site/protocol/contract-auctionhouse.mdx`
+**Environment Variables:**
+- `NEXT_PUBLIC_APP_URL`
+- `DATABASE_URL`
+- `SESSION_SECRET`
-- [ ] **Contract: FarcasterFrameRegistry**
- - Source: `packages/contracts/social/`
- - Suggested location: `docs-site/protocol/contract-farcasterframeregistry.mdx`
+**Build Command:** `pnpm --filter @castquest/web build`
-- [ ] **Contract: SocialAutomationConfig**
- - Source: `packages/contracts/social/`
- - Suggested location: `docs-site/protocol/contract-socialautomationconfig.mdx`
+**Test Command:** `pnpm --filter @castquest/web test`
-- [ ] **SDK: bridge**
- - Source: `/packages/sdk/bridge.ts`
- - Suggested location: `docs-site/sdk/sdk-bridge.mdx`
+**Section Coverage:**
-- [ ] **SDK: code**
- - Source: `/packages/sdk/code.ts`
- - Suggested location: `docs-site/sdk/sdk-code.mdx`
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ⚠️ build: PARTIAL
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
-- [ ] **SDK: game**
- - Source: `/packages/sdk/game.ts`
- - Suggested location: `docs-site/sdk/sdk-game.mdx`
+### ⚠️ Frames
-- [ ] **SDK: media**
- - Source: `/packages/sdk/media.ts`
- - Suggested location: `docs-site/sdk/sdk-media.mdx`
+**Status:** PARTIAL
-- [ ] **SDK: wallet**
- - Source: `/packages/sdk/wallet.ts`
- - Suggested location: `docs-site/sdk/sdk-wallet.mdx`
+**Code Path:** `apps/web/`
-- [ ] **Agent: AuctionAgent**
- - Source: `/packages/agents/AuctionAgent.ts`
- - Suggested location: `docs-site/agents/agent-auctionagent.mdx`
+**Docs Path:** `docs-site/frames/`
-- [ ] **Agent: CreationAgent**
- - Source: `/packages/agents/CreationAgent.ts`
- - Suggested location: `docs-site/agents/agent-creationagent.mdx`
+**Environment Variables:**
+- `FARCASTER_APP_FID`
+- `FARCASTER_APP_MNEMONIC`
-- [ ] **Agent: CurationAgent**
- - Source: `/packages/agents/CurationAgent.ts`
- - Suggested location: `docs-site/agents/agent-curationagent.mdx`
+**Build Command:** `pnpm --filter @castquest/web build`
-- [ ] **Agent: FrameAgent**
- - Source: `/packages/agents/FrameAgent.ts`
- - Suggested location: `docs-site/agents/agent-frameagent.mdx`
+**Section Coverage:**
-- [ ] **Agent: FraudAgent**
- - Source: `/packages/agents/FraudAgent.ts`
- - Suggested location: `docs-site/agents/agent-fraudagent.mdx`
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ✅ security: COMPLETE
-- [ ] **Agent: GameAgent**
- - Source: `/packages/agents/GameAgent.ts`
- - Suggested location: `docs-site/agents/agent-gameagent.mdx`
+### ❌ Quests
-- [ ] **Agent: PortfolioAgent**
- - Source: `/packages/agents/PortfolioAgent.ts`
- - Suggested location: `docs-site/agents/agent-portfolioagent.mdx`
+**Status:** INCOMPLETE
-- [ ] **Agent: PricingAgent**
- - Source: `/packages/agents/PricingAgent.ts`
- - Suggested location: `docs-site/agents/agent-pricingagent.mdx`
+**Code Path:** `apps/web/`
-- [ ] **Agent: SocialAutomationAgent**
- - Source: `/packages/agents/SocialAutomationAgent.ts`
- - Suggested location: `docs-site/agents/agent-socialautomationagent.mdx`
+**Docs Path:** `docs-site/quests/`
-- [ ] **Agent: SyncAgent**
- - Source: `/packages/agents/SyncAgent.ts`
- - Suggested location: `docs-site/agents/agent-syncagent.mdx`
+**Build Command:** `pnpm --filter @castquest/web build`
-- [ ] **Agent: UiAgent**
- - Source: `/packages/agents/UiAgent.ts`
- - Suggested location: `docs-site/agents/agent-uiagent.mdx`
+**Section Coverage:**
-### Existing Documentation Needing Completion
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
-- [ ] **admin-dashboard/alerts.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+### ⚠️ Mints
-- [ ] **admin-dashboard/audit-logs.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Status:** PARTIAL
-- [ ] **admin-dashboard/fee-controls.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Code Path:** `apps/web/`
-- [ ] **admin-dashboard/index.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Docs Path:** `docs-site/mints/`
-- [ ] **admin-dashboard/overview-metrics.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Build Command:** `pnpm --filter @castquest/web build`
-- [ ] **admin-dashboard/pause-protocol.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Section Coverage:**
-- [ ] **admin-dashboard/permissions.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ✅ security: COMPLETE
-- [ ] **admin-dashboard/protocol-fees.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+### ❌ Marketplace
-- [ ] **admin-dashboard/risk-management.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Status:** INCOMPLETE
-- [ ] **admin-dashboard/system-status.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Code Path:** `apps/web/`
-- [ ] **admin-dashboard/token-management.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Docs Path:** `docs-site/marketplace/`
-- [ ] **admin-dashboard/tvl-and-volume.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Build Command:** `pnpm --filter @castquest/web build`
-- [ ] **admin-dashboard/user-metrics.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+**Section Coverage:**
-- [ ] **agents/alerting-agents.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
-- [ ] **agents/automation-agents.mdx**
- - Add sections: Setup/Installation, Environment Variables, Usage/Runtime, Deployment, Security
+## Recommended Actions
+1. Complete all MISSING sections with actual content
+2. Expand PARTIAL sections with complete information
+3. Add cross-references to code paths in each doc
+4. Validate all commands and environment variable names
+5. Include security best practices in each feature doc
----
+## Validation Script
-## 7. Recommendations
+To run this validation:
+```bash
+pnpm validate:docs
+```
-### High Priority
-
-1. **Document missing features** - 26 features lack documentation
-2. **Fix consistency issues** - 0 inconsistencies found
-3. **Complete production readiness docs** - Address 0 blocker items
-
-### Medium Priority
-
-1. **Fill in missing sections** - 236 docs need completion
-2. **Enhance important production docs** - 0 items need attention
-3. **Create migration guides** - If not present
-
-### Low Priority
-
-1. **Add optional production docs** - 0 items
-2. **Improve cross-references** - Link related documentation
-3. **Add code examples** - Especially for SDK modules
-
----
-
-## 8. Notes
-
-- This is a **non-blocking, informational report**
-- No runtime or feature logic has been modified
-- All findings are recommendations for documentation improvement
-- Documentation validation should be run periodically as features evolve
-- Consider integrating validation into CI/CD as informational checks
-
----
-
-## 9. Validation Metadata
-
-- **Script:** `scripts/validate-docs.js`
-- **Repository Root:** `/home/runner/work/cast/cast`
-- **Documentation Root:** `/home/runner/work/cast/cast/docs-site`
-- **Analysis Date:** 1/19/2026, 9:05:31 AM
-- **Total Features Analyzed:** 55
-- **Total Docs Analyzed:** 241
-
----
-
-**End of Report**
+The script checks:
+- Existence of documentation files
+- Presence of required sections
+- Content completeness (not just templates)
+- Cross-references to code paths
diff --git a/docs-site/agents/index.mdx b/docs-site/agents/index.mdx
index e418895..845fd3c 100644
--- a/docs-site/agents/index.mdx
+++ b/docs-site/agents/index.mdx
@@ -1,60 +1,391 @@
----
-
-title: "Agents"
+---
+title: "Agents Overview"
section: "agents"
slug: "index"
-
-tags: ["agents"]
+tags: ["agents", "ai", "automation"]
weight: 0
navOrder: 0
---
-# Agents
+# AI Agents
-> CASTQUEST V3 — agents / $args[0].Value.ToUpper() gents
+> CASTQUEST V3 — Autonomous AI Agents for Protocol Operations
## Purpose
-Describe the purpose of this page in the CASTQUEST V3 protocol, including how it connects to:
-- Multi-chain protocol flows
-- Tokenized profiles and marketplace
-- Frames, quests, mints, and workers
-- Governance, buyback, and risk controls
+CASTQUEST V3 AI Agents are autonomous services that perform intelligent operations across the protocol:
+
+- **Content Creation**: Generate creative assets using AI models
+- **Market Intelligence**: Analyze trends and provide pricing insights
+- **Fraud Detection**: Identify and prevent malicious activity
+- **Curation**: Discover and rank high-quality content
+- **Automation**: Execute complex multi-step workflows
+- **Cross-chain Sync**: Maintain consistency across chains
+
+The agents participate in protocol revenue and operate with configurable autonomy levels.
+
+**Code Path:** `packages/agents/`
## Architecture
-Explain the core architecture for this topic:
-- Key contracts, agents, or services
-- Data flows and state transitions
-- Integration points (Farcaster, L3, external chains)
+### Agent Types
+
+CASTQUEST implements 11 specialized agents (see `packages/agents/index.ts`):
+
+```
+@castquest/agents
+├── CreationAgent.ts - Content generation (text, images, frames)
+├── PricingAgent.ts - Dynamic pricing & market analysis
+├── CurationAgent.ts - Content discovery & ranking
+├── FraudAgent.ts - Fraud detection & risk scoring
+├── AuctionAgent.ts - Automated bidding strategies
+├── FrameAgent.ts - Farcaster frame generation
+├── GameAgent.ts - Game asset generation
+├── SyncAgent.ts - Cross-chain synchronization
+├── UiAgent.ts - UI component generation
+├── PortfolioAgent.ts - Portfolio analysis
+└── SocialAutomationAgent.ts - Social media automation
+```
+
+### Technology Stack
+
+- **Runtime**: Node.js 18+, TypeScript
+- **AI Models**: OpenAI GPT-4, Anthropic Claude, Replicate
+- **Queue**: Redis for job management
+- **Storage**: PostgreSQL for agent state
+- **Build**: TypeScript Compiler (tsc)
+
+### System Design
+
+```
+┌─────────────┐
+│ Trigger │ (Event, Schedule, Manual)
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Job Queue │ (Redis)
+│ (Priority) │
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Agent Pool │ (Workers with concurrency limits)
+│ (5 workers) │
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ AI Services │ (OpenAI, Anthropic, Replicate)
+│ (External) │
+└──────┬──────┘
+ │
+ ▼
+┌─────────────┐
+│ Results │ (Stored in DB, emitted as events)
+└─────────────┘
+```
+
+### Integration Points
+
+1. **Protocol Events**: Agents listen to smart contract events
+2. **Marketplace**: Pricing and curation for listings
+3. **Frames**: Generate and validate Farcaster frames
+4. **Quests**: Automate quest verification
+5. **Governance**: Participate in DAO voting
+6. **External APIs**: Farcaster, OpenAI, social platforms
+
+## Key Flows
+
+### 1. Content Creation Flow
+
+**Actors**: User, CreationAgent, AI Service, IPFS
+**Trigger**: User requests content generation
+
+```typescript
+// User initiates creation
+const job = await agents.creation.generate({
+ type: 'image',
+ prompt: 'Cyberpunk city with neon lights',
+ style: 'digital-art'
+});
+
+// Agent processes
+// 1. Validates input
+// 2. Calls AI service (Replicate)
+// 3. Stores result in IPFS
+// 4. Returns metadata
+```
+
+**Outputs**: IPFS hash, metadata, quality score
+**Failure Modes**:
+- AI service timeout → Retry with exponential backoff
+- Content policy violation → Reject with explanation
+- Storage failure → Cache locally, retry upload
+
+### 2. Fraud Detection Flow
+
+**Actors**: FraudAgent, Transaction Monitor, Risk Database
+**Trigger**: Suspicious activity detected
+
+```typescript
+// Continuous monitoring
+agents.fraud.monitor({
+ transactionHash: '0x...',
+ walletAddress: '0x...',
+ amount: '1000000000000000000'
+});
+
+// Agent analyzes
+// 1. Historical patterns
+// 2. Risk indicators
+// 3. ML model scoring
+// 4. Issues alerts if needed
+```
+
+**Outputs**: Risk score (0-100), alert level, recommended action
+**Safeguards**:
+- Human review for high-risk (score > 80)
+- Automated pause for critical risk (score > 95)
+- Appeal process for false positives
+
+### 3. Dynamic Pricing Flow
+
+**Actors**: PricingAgent, Market Data, Marketplace
+**Trigger**: New listing or price update request
+
+```typescript
+// Automatic pricing
+const price = await agents.pricing.calculate({
+ itemId: 'frame-123',
+ category: 'frames',
+ attributes: { rarity: 'legendary', creator: '0x...' }
+});
+
+// Agent considers
+// 1. Historical sales
+// 2. Similar items
+// 3. Market trends
+// 4. Supply/demand
+```
+
+**Outputs**: Recommended price, confidence score, price range
+**Failure Modes**:
+- Insufficient data → Use category average
+- Market volatility → Widen price range
+- Data staleness → Refresh and recalculate
+
+## Build & Runtime
+
+### Build Commands
+
+```bash
+# Build agents service
+pnpm --filter @castquest/agents build
+
+# Type check
+pnpm --filter @castquest/agents typecheck
+
+# Lint
+pnpm --filter @castquest/agents lint
+
+# Test
+pnpm --filter @castquest/agents test
+```
+
+### Runtime Commands
+
+```bash
+# Development mode (watch)
+pnpm --filter @castquest/agents dev
+
+# Production mode
+pnpm --filter @castquest/agents start
+
+# With PM2 (recommended for production)
+pm2 start packages/agents/dist/index.js --name agents
+```
-## Flows
+### Environment Requirements
-Describe the primary flows:
-- Actors
-- Inputs
-- Outputs
-- Failure modes and safeguards
+- Node.js >= 18.18.0
+- PostgreSQL >= 13 (for state storage)
+- Redis >= 6 (for job queue)
+- OpenAI API key (required)
+- Anthropic API key (recommended)
+- Replicate API key (for image generation)
+
+### Resource Requirements
+
+- **CPU**: 2+ cores (4+ recommended)
+- **Memory**: 2GB minimum (4GB recommended)
+- **Storage**: 10GB minimum (logs, cache)
+- **Network**: Stable internet (AI API calls)
+
+## Deployment
+
+### Docker Deployment
+
+```bash
+# Build image
+docker build -t castquest/agents:3.0.0 -f infra/docker/Dockerfile.agents .
+
+# Run container
+docker run -d \
+ --name castquest-agents \
+ -p 3001:3001 \
+ --env-file .env \
+ castquest/agents:3.0.0
+```
+
+### Kubernetes Deployment
+
+```bash
+# Deploy to staging
+kubectl apply -f infra/k8s/staging/agents-deployment.yaml
+
+# Deploy to production
+kubectl apply -f infra/k8s/production/agents-deployment.yaml
+
+# Check status
+kubectl get pods -l app=castquest-agents
+```
+
+### Health Checks
+
+Agents expose health endpoints:
+- `GET /health` - Overall health status
+- `GET /health/live` - Liveness probe
+- `GET /health/ready` - Readiness probe
+
+### Scaling
+
+Horizontal scaling via Kubernetes HPA:
+- Min replicas: 2
+- Max replicas: 10
+- Target CPU: 70%
+- Target Memory: 80%
+
+## Security
+
+### API Key Management
+
+- **Storage**: Use secrets manager (AWS Secrets Manager, Vault)
+- **Rotation**: Rotate keys every 90 days
+- **Monitoring**: Track API usage for anomalies
+- **Least Privilege**: Each agent has minimum required permissions
+
+### Rate Limiting
+
+Agents implement intelligent rate limiting:
+- Respect AI service rate limits
+- Queue requests during high load
+- Exponential backoff on errors
+- Fair distribution across agent types
+
+### Input Validation
+
+All agent inputs are validated:
+- Content length limits (max 10,000 chars)
+- Sanitization of user input (XSS prevention)
+- Schema validation (JSON Schema)
+- Timeout enforcement (5 min max)
+
+### Network Security
+
+- HTTPS for all external API calls
+- TLS 1.2+ required
+- Certificate validation enabled
+- VPC isolation in production
+- Firewall rules (restrict outbound)
+
+### Audit Logging
+
+All agent actions are logged:
+- Timestamp, agent type, job ID
+- Input parameters (sanitized)
+- Output/result
+- Execution time
+- Success/failure status
## Metrics & Observability
-List the key metrics, dashboards, and alerts relevant to this topic.
+### Key Metrics
+
+Monitor these metrics in production:
+
+- **Throughput**: Jobs processed per minute
+- **Latency**: p50, p95, p99 execution time
+- **Success Rate**: % of successful executions
+- **Error Rate**: % of failed executions
+- **Queue Depth**: Number of pending jobs
+- **API Usage**: Calls per service (OpenAI, Anthropic)
+- **Cost**: API costs per agent type
+
+### Dashboards
+
+Agents expose Prometheus metrics at `/metrics`:
+
+```
+# Agent execution time (histogram)
+agent_execution_duration_seconds{agent="pricing"}
+
+# Job success/failure (counter)
+agent_jobs_total{agent="fraud",status="success"}
+
+# Queue depth (gauge)
+agent_queue_depth{priority="high"}
+
+# API rate limits (gauge)
+agent_api_limit_remaining{service="openai"}
+```
+
+### Alerts
+
+Recommended alerts:
+- High error rate (>5% for 5min)
+- API rate limit approaching (>80%)
+- Queue depth high (>1000 jobs)
+- Slow execution (>2x baseline)
+- Database connection failures
+- Memory usage high (>85%)
## Implementation Notes
-Add implementation details, edge cases, and migration notes.
+### Agent State Machine
-## Next Steps
+Each agent follows a state machine:
+1. **IDLE**: Waiting for jobs
+2. **PROCESSING**: Executing job
+3. **SUCCESS**: Completed successfully
+4. **FAILED**: Execution failed
+5. **RETRY**: Retrying after failure
+
+### Retry Logic
-Link to:
-- Related protocol pages
-- Builder guides
-- SDK references
-- Admin dashboard views
+- Max retries: 3
+- Backoff: Exponential (1s, 2s, 4s)
+- Retry on: Timeout, rate limit, service error
+- No retry on: Invalid input, policy violation
+### Cost Management
+AI service calls can be expensive:
+- Cache common requests (Redis, 1 hour TTL)
+- Batch similar requests when possible
+- Use cheaper models for simple tasks
+- Set monthly budget limits
+- Monitor per-agent costs
+
+## Next Steps
+- [Setup & Configuration](/agents/setup) - Environment setup
+- [Custom Agents](/agents/custom) - Build custom agents
+- [API Reference](/agents/api-reference) - Agent API docs
+- [Monitoring](/agents/monitoring) - Production monitoring
-## Diagram
+## Support
-Describe or embed the key architecture or flow diagram for this topic here.
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/agents
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/agents/setup.mdx b/docs-site/agents/setup.mdx
new file mode 100644
index 0000000..d12788d
--- /dev/null
+++ b/docs-site/agents/setup.mdx
@@ -0,0 +1,424 @@
+---
+title: "Agents Setup & Configuration"
+section: "agents"
+slug: "setup"
+tags: ["agents", "setup", "ai"]
+weight: 1
+navOrder: 1
+---
+
+# Agents Setup & Configuration
+
+> CASTQUEST V3 — AI Agents Setup Guide
+
+## Overview
+
+The CASTQUEST Agents service (`@castquest/agents`) provides autonomous AI agents that perform various protocol operations including pricing, curation, fraud detection, and social automation.
+
+**Code Path:** `packages/agents/`
+
+## Prerequisites
+
+Before setting up the agents service:
+
+- **Node.js**: >= 18.18.0
+- **TypeScript**: >= 5.3.3
+- **OpenAI API Access**: For AI capabilities
+- **Database**: PostgreSQL for agent state
+- **Redis**: For job queuing and caching
+
+## Installation
+
+### From Repository Root
+
+```bash
+# Install all dependencies
+pnpm install
+
+# Build agents package
+pnpm --filter @castquest/agents build
+```
+
+### From Agents Directory
+
+```bash
+cd packages/agents
+pnpm install
+pnpm run build
+```
+
+## Environment Variables
+
+### Required Variables
+
+Configure these environment variables for agents to function:
+
+#### AI Service API Keys
+
+- **`OPENAI_API_KEY`**: OpenAI API key for GPT models
+ - Obtain from: https://platform.openai.com/api-keys
+ - Example: `sk-proj-...`
+ - Used by: All agents for language processing
+
+- **`ANTHROPIC_API_KEY`**: Anthropic Claude API key
+ - Obtain from: https://console.anthropic.com/
+ - Example: `sk-ant-...`
+ - Used by: CreationAgent, CurationAgent
+
+- **`REPLICATE_API_KEY`**: Replicate API key for image generation
+ - Obtain from: https://replicate.com/account/api-tokens
+ - Example: `r8_...`
+ - Used by: GameAgent, FrameAgent
+
+#### Database Configuration
+
+- **`DATABASE_URL`**: PostgreSQL connection string
+ - Format: `postgresql://user:password@host:5432/database`
+ - Example: `postgresql://castquest:secret@localhost:5432/castquest`
+ - Used for: Agent state, job history, results storage
+
+- **`REDIS_URL`**: Redis connection string
+ - Format: `redis://host:port`
+ - Example: `redis://localhost:6379`
+ - Used for: Job queue, caching, rate limiting
+
+#### Network Configuration
+
+- **`BASE_RPC_URL`**: Base network RPC endpoint
+ - Example: `https://mainnet.base.org`
+ - Required for: On-chain data access
+
+- **`ETHEREUM_RPC_URL`**: Ethereum mainnet RPC endpoint
+ - Example: `https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY`
+ - Optional: For cross-chain operations
+
+### Optional Variables
+
+- **`AGENTS_PORT`**: HTTP port for agents API (default: 3001)
+- **`AGENTS_LOG_LEVEL`**: Logging level (default: 'info')
+ - Options: 'debug', 'info', 'warn', 'error'
+- **`AGENTS_CONCURRENCY`**: Max concurrent agent executions (default: 5)
+- **`AGENTS_TIMEOUT`**: Agent execution timeout in ms (default: 300000)
+
+### Example `.env` file
+
+```bash
+# AI Service Keys
+OPENAI_API_KEY=sk-proj-1234567890abcdef
+ANTHROPIC_API_KEY=sk-ant-1234567890abcdef
+REPLICATE_API_KEY=r8_1234567890abcdef
+
+# Database
+DATABASE_URL=postgresql://castquest:password@localhost:5432/castquest
+REDIS_URL=redis://localhost:6379
+
+# Network
+BASE_RPC_URL=https://mainnet.base.org
+ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY
+
+# Optional
+AGENTS_PORT=3001
+AGENTS_LOG_LEVEL=info
+AGENTS_CONCURRENCY=5
+AGENTS_TIMEOUT=300000
+```
+
+## Agent Types
+
+The following agents are available (see `packages/agents/index.ts`):
+
+### 1. **CreationAgent** (`packages/agents/CreationAgent.ts`)
+ - Generates creative content (text, images)
+ - Validates content quality
+ - Applies protocol guidelines
+
+### 2. **PricingAgent** (`packages/agents/PricingAgent.ts`)
+ - Dynamic pricing for marketplace items
+ - Market analysis and trends
+ - Price recommendations
+
+### 3. **CurationAgent** (`packages/agents/CurationAgent.ts`)
+ - Content discovery and ranking
+ - Quality assessment
+ - Trend identification
+
+### 4. **FraudAgent** (`packages/agents/FraudAgent.ts`)
+ - Detects fraudulent activity
+ - Pattern analysis
+ - Risk scoring
+
+### 5. **AuctionAgent** (`packages/agents/AuctionAgent.ts`)
+ - Automated bidding strategies
+ - Auction monitoring
+ - Price optimization
+
+### 6. **FrameAgent** (`packages/agents/FrameAgent.ts`)
+ - Farcaster frame generation
+ - Frame validation
+ - Metadata optimization
+
+### 7. **GameAgent** (`packages/agents/GameAgent.ts`)
+ - Game asset generation
+ - Balance testing
+ - Gameplay optimization
+
+### 8. **SyncAgent** (`packages/agents/SyncAgent.ts`)
+ - Cross-chain synchronization
+ - State consistency checks
+ - Data reconciliation
+
+### 9. **UiAgent** (`packages/agents/UiAgent.ts`)
+ - UI component generation
+ - Layout optimization
+ - Accessibility checks
+
+### 10. **PortfolioAgent** (`packages/agents/PortfolioAgent.ts`)
+ - Portfolio analysis
+ - Investment recommendations
+ - Risk assessment
+
+### 11. **SocialAutomationAgent** (`packages/agents/SocialAutomationAgent.ts`)
+ - Social media posting
+ - Engagement tracking
+ - Community management
+
+## Build & Development
+
+### Building
+
+```bash
+# From repository root
+pnpm --filter @castquest/agents build
+
+# From agents directory
+pnpm run build
+```
+
+**Build Output:** `packages/agents/dist/` (TypeScript compiled to JavaScript)
+
+### Running in Development
+
+```bash
+# Watch mode with auto-reload
+pnpm --filter @castquest/agents dev
+
+# Or from agents directory
+pnpm run dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm --filter @castquest/agents test
+
+# Watch mode
+pnpm --filter @castquest/agents test:watch
+```
+
+### Type Checking
+
+```bash
+pnpm --filter @castquest/agents typecheck
+```
+
+## Deployment
+
+### Docker Deployment
+
+Agents can be deployed using Docker:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY packages/agents/package.json ./
+COPY packages/agents/dist ./dist
+
+RUN npm install --production
+
+EXPOSE 3001
+
+CMD ["node", "dist/index.js"]
+```
+
+Build and run:
+
+```bash
+docker build -t castquest-agents -f infra/docker/Dockerfile.agents .
+docker run -p 3001:3001 --env-file .env castquest-agents
+```
+
+### Kubernetes Deployment
+
+Deploy to Kubernetes using provided manifests:
+
+```bash
+# Apply staging deployment
+kubectl apply -f infra/k8s/staging/agents-deployment.yaml
+
+# Apply production deployment
+kubectl apply -f infra/k8s/production/agents-deployment.yaml
+```
+
+### Process Management
+
+For production deployment without containers:
+
+```bash
+# Using PM2
+pm2 start packages/agents/dist/index.js --name castquest-agents
+
+# Using systemd
+sudo systemctl start castquest-agents
+```
+
+## Security
+
+### API Key Security
+
+- **Never commit API keys** to version control
+- Use secrets management (AWS Secrets Manager, HashiCorp Vault)
+- Rotate keys every 90 days
+- Monitor API usage for anomalies
+
+### Rate Limiting
+
+AI service providers have rate limits:
+- OpenAI: 3,500 requests/min (varies by tier)
+- Anthropic: 1,000 requests/min
+- Replicate: 500 requests/min
+
+The agents service implements:
+- Request queuing with Redis
+- Exponential backoff on rate limit errors
+- Fair distribution across agent types
+
+### Input Validation
+
+All agent inputs are validated:
+- Content length limits
+- Sanitization of user input
+- Schema validation
+- Timeout enforcement
+
+### Secrets Management
+
+Example using AWS Secrets Manager:
+
+```typescript
+import { SecretsManager } from 'aws-sdk';
+
+const secretsManager = new SecretsManager();
+const secret = await secretsManager.getSecretValue({
+ SecretId: 'castquest/agents/api-keys'
+}).promise();
+
+const apiKeys = JSON.parse(secret.SecretString);
+```
+
+### Network Security
+
+- All API calls use HTTPS/TLS
+- Validate SSL certificates
+- Use VPC endpoints for AWS services
+- Implement firewall rules (allow only necessary ports)
+
+## Monitoring & Observability
+
+### Health Checks
+
+Agents expose health check endpoints:
+
+```bash
+curl http://localhost:3001/health
+```
+
+Response:
+```json
+{
+ "status": "healthy",
+ "agents": {
+ "creation": "running",
+ "pricing": "running",
+ "fraud": "running"
+ },
+ "dependencies": {
+ "database": "connected",
+ "redis": "connected",
+ "openai": "accessible"
+ }
+}
+```
+
+### Metrics
+
+Key metrics to monitor:
+- Agent execution time (p50, p95, p99)
+- Success/failure rates per agent type
+- API rate limit hits
+- Queue depth
+- Database connection pool usage
+
+### Logging
+
+Configure structured logging:
+
+```typescript
+import { createLogger } from './logger';
+
+const logger = createLogger({
+ level: process.env.AGENTS_LOG_LEVEL || 'info',
+ service: 'agents'
+});
+
+logger.info('Agent started', { agentType: 'pricing', jobId: '123' });
+```
+
+### Alerts
+
+Set up alerts for:
+- Agent failures (> 5% error rate)
+- API rate limit errors
+- Database connection failures
+- High queue depth (> 1000 jobs)
+- Slow execution times (> 2x baseline)
+
+## Troubleshooting
+
+### Common Issues
+
+**"OpenAI API key invalid"**
+- Verify `OPENAI_API_KEY` is set correctly
+- Check key hasn't been revoked
+- Test with: `curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"`
+
+**"Database connection failed"**
+- Verify `DATABASE_URL` format
+- Check PostgreSQL is running
+- Ensure firewall allows connection
+- Test with: `psql $DATABASE_URL`
+
+**"Redis connection timeout"**
+- Verify `REDIS_URL` is correct
+- Check Redis is running: `redis-cli ping`
+- Ensure network connectivity
+
+**Agent execution timeout**
+- Increase `AGENTS_TIMEOUT` value
+- Check AI service latency
+- Review agent logic for inefficiencies
+
+## Next Steps
+
+- [Agent Architecture](/agents/architecture) - Deep dive into agent design
+- [Agent API Reference](/agents/api-reference) - API documentation
+- [Custom Agents](/agents/custom) - Creating custom agents
+- [Agent Monitoring](/agents/monitoring) - Production monitoring guide
+
+## Support
+
+- **GitHub Issues**: https://github.com/CastQuest/cast/issues
+- **Documentation**: https://docs.castquest.io/agents
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/frames/setup.mdx b/docs-site/frames/setup.mdx
new file mode 100644
index 0000000..6f7156d
--- /dev/null
+++ 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
diff --git a/docs-site/marketplace/setup.mdx b/docs-site/marketplace/setup.mdx
new file mode 100644
index 0000000..122ef8f
--- /dev/null
+++ b/docs-site/marketplace/setup.mdx
@@ -0,0 +1,302 @@
+---
+title: "Marketplace Setup & Configuration"
+section: "marketplace"
+slug: "setup"
+tags: ["marketplace", "trading", "setup"]
+weight: 1
+navOrder: 1
+---
+
+# Marketplace Setup & Configuration
+
+> CASTQUEST V3 — Marketplace Configuration Guide
+
+## Overview
+
+The CASTQUEST marketplace enables users to list, buy, sell, and auction digital assets including NFTs, tokens, and other protocol items. It supports multi-chain trading, royalties, and complex auction mechanisms.
+
+**Code Path:** `apps/web/app/marketplace/` (part of web application)
+
+## Architecture
+
+### Marketplace Components
+
+- **Listing Engine**: Create and manage listings
+- **Order Matching**: Match buyers and sellers
+- **Auction System**: Dutch and English auctions
+- **Royalty Distribution**: Automatic royalty payments
+- **Cross-chain Trading**: Bridge and settlement
+
+### Trading Types
+
+- **Fixed Price**: Simple buy now listings
+- **Auctions**: Time-based bidding
+- **Offers**: Make offers on listed items
+- **Bundles**: Multi-item packages
+- **Cross-chain**: Trade across different chains
+
+## Prerequisites
+
+- Web application setup (see Web App Setup)
+- Marketplace contracts deployed
+- Database configured (for orders and listings)
+- Indexer running (for order book)
+
+## Environment Variables
+
+Marketplace uses web app environment variables plus:
+
+### Contract Addresses
+
+- **`NEXT_PUBLIC_MARKETPLACE_ADDRESS`**: Main marketplace contract
+- **`NEXT_PUBLIC_AUCTION_HOUSE_ADDRESS`**: Auction contract
+- **`NEXT_PUBLIC_ROYALTY_REGISTRY_ADDRESS`**: Royalty registry
+
+### Configuration
+
+- **`MARKETPLACE_FEE_BPS`**: Marketplace fee in basis points (default: 250 = 2.5%)
+- **`MIN_BID_INCREMENT_BPS`**: Minimum bid increment (default: 500 = 5%)
+
+## Setup Steps
+
+### 1. Deploy Marketplace Contracts
+
+Deploy marketplace smart contracts:
+
+```bash
+# Deploy marketplace contracts
+pnpm --filter @castquest/contracts deploy:base
+
+# Verify deployment
+npx hardhat verify --network base CONTRACT_ADDRESS
+```
+
+### 2. Configure Royalties
+
+Set up royalty registry:
+
+```typescript
+// Configure default royalty
+await royaltyRegistry.setDefaultRoyalty(
+ treasuryAddress,
+ 250 // 2.5%
+);
+
+// Set collection-specific royalty
+await royaltyRegistry.setRoyaltyForCollection(
+ nftAddress,
+ creatorAddress,
+ 500 // 5%
+);
+```
+
+### 3. Initialize Marketplace
+
+Configure marketplace settings:
+
+```bash
+# Set marketplace fee
+pnpm run marketplace:set-fee --fee 250
+
+# Set minimum listing duration
+pnpm run marketplace:set-min-duration --duration 3600
+
+# Set payment tokens
+pnpm run marketplace:add-payment-token --token 0x...
+```
+
+## Build & Development
+
+Marketplace is part of the web application:
+
+```bash
+# Development
+pnpm --filter @castquest/web dev
+
+# Build
+pnpm --filter @castquest/web build
+
+# Test marketplace routes
+curl http://localhost:3000/api/marketplace
+```
+
+## Deployment
+
+### Marketplace Configuration
+
+Deploy marketplace by:
+
+1. **Deploy Contracts**: Deploy marketplace contracts to chain
+2. **Configure Settings**: Set fees, payment tokens, durations
+3. **Initialize Indexer**: Start indexing marketplace events
+4. **Launch Frontend**: Deploy web application with marketplace
+
+### Payment Tokens
+
+Configure accepted payment tokens:
+
+```bash
+# Add payment token
+pnpm run marketplace:add-token \
+ --address 0x... \
+ --symbol ETH \
+ --decimals 18
+
+# Add stablecoin
+pnpm run marketplace:add-token \
+ --address 0x... \
+ --symbol USDC \
+ --decimals 6
+```
+
+## Security
+
+### Trading Security
+
+- **Order Validation**: Verify all order parameters
+- **Signature Verification**: Validate cryptographic signatures
+- **Balance Checks**: Ensure sufficient balance before trade
+- **Reentrancy Protection**: Prevent reentrancy attacks
+- **Front-running Prevention**: Use commit-reveal for auctions
+
+### Payment Security
+
+- **Escrow**: Hold payments in secure contract
+- **Atomic Swaps**: Execute trades atomically
+- **Refund Mechanism**: Handle failed trades
+- **Fee Validation**: Verify fee calculations
+
+### Marketplace Security Checklist
+
+Before launching:
+
+- [ ] Smart contracts audited by professional firm
+- [ ] All functions have reentrancy protection
+- [ ] Fee calculations verified
+- [ ] Royalty distribution tested
+- [ ] Payment token whitelist configured
+- [ ] Emergency pause mechanism tested
+- [ ] Admin multisig configured
+- [ ] Rate limiting implemented
+- [ ] Signature verification working
+- [ ] Monitoring and alerts configured
+
+### Ongoing Security
+
+Maintain security post-launch:
+
+- **Regular audits**: Annual security audits
+- **Bug bounty**: Active bug bounty program
+- **Monitoring**: 24/7 security monitoring
+- **Incident response**: Documented response procedures
+- **Key rotation**: Regular key rotation
+- **Contract upgrades**: Secure upgrade process
+
+## Monitoring
+
+### Marketplace Metrics
+
+Track marketplace activity:
+- Total listings
+- Active orders
+- Trade volume (24h, 7d, 30d)
+- Unique traders
+- Average sale price
+- Royalty distribution
+
+### Performance
+
+Monitor marketplace performance:
+- Order matching latency
+- Transaction confirmation time
+- API response times
+- Database query performance
+- Indexer sync lag
+
+## Marketplace Operations
+
+### Creating Listings
+
+List items via API:
+
+```typescript
+POST /api/marketplace/listings
+{
+ "tokenAddress": "0x...",
+ "tokenId": "123",
+ "price": "1000000000000000000", // 1 ETH
+ "paymentToken": "0x...",
+ "duration": 86400, // 24 hours
+ "listingType": "fixed"
+}
+```
+
+### Managing Auctions
+
+Create auction:
+
+```typescript
+POST /api/marketplace/auctions
+{
+ "tokenAddress": "0x...",
+ "tokenId": "456",
+ "startingPrice": "500000000000000000", // 0.5 ETH
+ "reservePrice": "1000000000000000000", // 1 ETH
+ "duration": 86400,
+ "auctionType": "english"
+}
+```
+
+### Order Book
+
+View order book:
+
+```bash
+# Get all listings
+curl https://api.castquest.io/api/marketplace/listings
+
+# Get specific item
+curl https://api.castquest.io/api/marketplace/items/0x.../123
+
+# Get user orders
+curl https://api.castquest.io/api/marketplace/users/0x.../orders
+```
+
+## Troubleshooting
+
+**"Listing creation failed"**
+- Verify user owns asset
+- Check asset is approved for marketplace
+- Ensure price is valid
+- Review gas limits
+
+**"Purchase failed"**
+- Check buyer has sufficient balance
+- Verify listing is active
+- Check payment token is approved
+- Review marketplace contract state
+
+**"Auction bid rejected"**
+- Verify bid meets minimum increment
+- Check auction is active
+- Ensure user has sufficient balance
+- Review previous bid amount
+
+**"Royalty distribution failed"**
+- Verify royalty registry is configured
+- Check recipient addresses are valid
+- Ensure sufficient payment for royalties
+- Review royalty percentage
+
+## Next Steps
+
+- [Marketplace Listings](/marketplace/listings) - Listing management
+- [Auctions](/marketplace/auctions) - Auction mechanisms
+- [Royalties](/marketplace/royalties) - Royalty configuration
+- [Marketplace API](/reference/api-reference#marketplace) - API docs
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/marketplace
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/mints/setup.mdx b/docs-site/mints/setup.mdx
new file mode 100644
index 0000000..e06bc8d
--- /dev/null
+++ b/docs-site/mints/setup.mdx
@@ -0,0 +1,284 @@
+---
+title: "Mints Setup & Configuration"
+section: "mints"
+slug: "setup"
+tags: ["mints", "nft", "setup"]
+weight: 1
+navOrder: 1
+---
+
+# Mints Setup & Configuration
+
+> CASTQUEST V3 — NFT Minting System Configuration Guide
+
+## Overview
+
+The minting system allows users to mint NFTs, tokens, and other digital assets. It supports various mint types, pricing models, and eligibility criteria.
+
+**Code Path:** `apps/web/app/mints/` (part of web application)
+
+## Architecture
+
+### Mint System Components
+
+- **Mint Engine**: Core minting logic and smart contract interaction
+- **Eligibility**: Whitelist, allowlist, and criteria checking
+- **Pricing**: Dynamic pricing, auctions, and free mints
+- **Metadata**: IPFS storage and on-chain metadata
+- **Analytics**: Mint tracking and reporting
+
+### Mint Types
+
+- **Open Mints**: Public minting with no restrictions
+- **Whitelist Mints**: Restricted to approved addresses
+- **Tiered Mints**: Different prices for different tiers
+- **Auction Mints**: Dutch auctions or English auctions
+- **Free Mints**: No cost minting (gas only)
+
+## Prerequisites
+
+- Web application setup (see Web App Setup)
+- Smart contracts deployed (minting contracts)
+- IPFS/Pinata configured (for metadata)
+- Database configured (for mint state)
+
+## Environment Variables
+
+Mints use web app environment variables plus:
+
+### Storage Configuration
+
+- **`PINATA_API_KEY`**: Pinata API key for IPFS
+- **`PINATA_SECRET_KEY`**: Pinata secret key
+- **`IPFS_GATEWAY_URL`**: IPFS gateway URL
+ - Example: `https://gateway.pinata.cloud`
+
+### Contract Addresses
+
+- **`NEXT_PUBLIC_MINT_FACTORY_ADDRESS`**: Mint factory contract
+- **`NEXT_PUBLIC_NFT_ADDRESS`**: NFT contract address
+
+## Setup Steps
+
+### 1. Configure IPFS Storage
+
+Set up Pinata for metadata storage:
+
+```bash
+# Add to .env.production
+PINATA_API_KEY=your_pinata_api_key
+PINATA_SECRET_KEY=your_pinata_secret_key
+IPFS_GATEWAY_URL=https://gateway.pinata.cloud
+```
+
+### 2. Deploy Minting Contracts
+
+Deploy NFT and minting contracts:
+
+```bash
+# Deploy contracts
+pnpm --filter @castquest/contracts deploy:base
+
+# Note contract addresses
+# Update environment variables
+```
+
+### 3. Initialize Mint Factory
+
+Configure mint factory:
+
+```typescript
+// Initialize mint settings
+await mintFactory.initialize({
+ maxSupply: 10000,
+ basePrice: ethers.parseEther("0.01"),
+ royaltyBps: 500 // 5%
+});
+```
+
+## Build & Development
+
+Mints are part of the web application:
+
+```bash
+# Development
+pnpm --filter @castquest/web dev
+
+# Build
+pnpm --filter @castquest/web build
+
+# Test mint routes
+curl http://localhost:3000/api/mints
+```
+
+## Deployment
+
+### Mint Configuration
+
+Deploy mint campaigns:
+
+1. **Create Mint Collection**: Define NFT collection
+2. **Set Pricing**: Configure mint price and tiers
+3. **Upload Metadata**: Upload to IPFS
+4. **Set Eligibility**: Configure whitelist or criteria
+5. **Launch**: Publish mint to users
+
+### Metadata Upload
+
+Upload metadata to IPFS:
+
+```bash
+# Upload metadata
+pnpm run mint:upload-metadata --collection my-collection
+
+# Returns IPFS hash
+# Update contract with base URI
+```
+
+## Minting and Metadata Security
+
+### Minting Security
+
+- **Reentrancy Protection**: All mint functions protected
+- **Supply Limits**: Enforce maximum supply
+- **Price Validation**: Verify payment amounts
+- **Signature Verification**: Validate whitelist signatures
+
+### Metadata Security
+
+- **IPFS Pinning**: Ensure metadata persistence
+- **Content Validation**: Verify uploaded content
+- **Duplicate Prevention**: Check for duplicate uploads
+- **Access Control**: Restrict metadata updates
+
+## Security Best Practices
+
+### Post-Deployment Security
+
+After deploying mints:
+
+- **Monitor mints**: Track all mint transactions
+- **Verify metadata**: Ensure IPFS content is correct
+- **Check contract state**: Verify supply and pricing
+- **Review access control**: Ensure proper permissions
+- **Test emergency pause**: Verify pause mechanism works
+
+### Security Audit Checklist
+
+Before launching mints:
+
+- [ ] Smart contracts audited
+- [ ] Metadata uploaded and pinned to IPFS
+- [ ] Supply limits configured
+- [ ] Pricing validated
+- [ ] Whitelist tested
+- [ ] Refund mechanism tested
+- [ ] Emergency pause tested
+- [ ] Gas limits configured
+- [ ] Access control verified
+- [ ] Monitoring configured
+
+## Monitoring
+
+### Mint Metrics
+
+Track mint performance:
+- Total mints
+- Mint success rate
+- Average mint price
+- Revenue generated
+- Failed mint reasons
+
+### Performance
+
+Monitor minting performance:
+- Transaction confirmation time
+- Metadata upload latency
+- IPFS gateway response time
+- Contract call success rate
+
+## Mint Operations
+
+### Creating Mint Campaigns
+
+Create via admin API:
+
+```typescript
+POST /api/admin/mints
+{
+ "name": "Genesis Collection",
+ "supply": 10000,
+ "price": "0.01",
+ "startDate": "2026-02-01T00:00:00Z",
+ "endDate": "2026-03-01T00:00:00Z",
+ "metadata": {
+ "baseURI": "ipfs://QmXXXXXX/"
+ }
+}
+```
+
+### Managing Whitelist
+
+Configure whitelist:
+
+```bash
+# Add to whitelist
+pnpm run mint:whitelist-add --addresses 0x...,0x...,0x...
+
+# Remove from whitelist
+pnpm run mint:whitelist-remove --addresses 0x...
+
+# Export whitelist
+pnpm run mint:whitelist-export
+```
+
+### Mint Analytics
+
+View mint analytics:
+
+```bash
+# Get mint stats
+curl https://api.castquest.io/api/mints/stats
+
+# Get collection stats
+curl https://api.castquest.io/api/mints/collection/123/stats
+```
+
+## Troubleshooting
+
+**"Mint failed"**
+- Check user has sufficient balance
+- Verify contract has remaining supply
+- Check mint is active
+- Review gas limits
+
+**"Metadata not found"**
+- Verify IPFS hash is correct
+- Check IPFS gateway is accessible
+- Ensure metadata is pinned
+- Try alternative gateway
+
+**"Not whitelisted"**
+- Verify address is on whitelist
+- Check signature is valid
+- Verify mint type allows whitelist
+- Review eligibility criteria
+
+**"Price mismatch"**
+- Check current mint price
+- Verify payment amount
+- Check for price tiers
+- Review transaction value
+
+## Next Steps
+
+- [Mint Types](/mints/mint-types) - Available mint types
+- [Mint Pricing](/mints/mint-pricing) - Pricing strategies
+- [Mint Eligibility](/mints/mint-eligibility) - Eligibility criteria
+- [Mint API](/reference/api-reference#mints) - API documentation
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/mints
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/overview/indexer-setup.mdx b/docs-site/overview/indexer-setup.mdx
new file mode 100644
index 0000000..c193d8c
--- /dev/null
+++ b/docs-site/overview/indexer-setup.mdx
@@ -0,0 +1,542 @@
+---
+title: "Indexer Setup & Configuration"
+section: "overview"
+slug: "indexer-setup"
+tags: ["indexer", "setup", "blockchain"]
+weight: 20
+navOrder: 20
+---
+
+# Indexer Setup & Configuration
+
+> CASTQUEST V3 — Blockchain Indexer Service
+
+## Overview
+
+The CASTQUEST Indexer (`@castquest/indexer`) is a blockchain indexing service that monitors on-chain events, indexes transaction data, and maintains a queryable database of protocol activity across multiple chains.
+
+**Code Path:** `packages/indexer/`
+
+## Purpose
+
+The indexer provides:
+- **Real-time Event Monitoring**: Tracks smart contract events across chains
+- **Historical Data**: Maintains complete transaction history
+- **Query Interface**: Fast access to on-chain data via REST API
+- **Cross-chain Synchronization**: Unified view of multi-chain activity
+- **Data Analytics**: Aggregated metrics and statistics
+
+### Components
+
+The indexer consists of three main modules (see `packages/indexer/`):
+
+1. **`buyback-indexer.ts`**: Indexes buyback transactions and treasury operations
+2. **`mc-indexer.ts`**: Multi-chain indexer for cross-chain tracking
+3. **`social-indexer.ts`**: Indexes social interactions (Farcaster frames, user activity)
+
+## Prerequisites
+
+- **Node.js**: >= 18.18.0
+- **PostgreSQL**: >= 13 (for data storage)
+- **Redis**: >= 6 (for caching and rate limiting)
+- **RPC Access**: Reliable RPC endpoints for each chain
+
+## Installation
+
+### From Repository Root
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build indexer
+pnpm --filter @castquest/indexer build
+```
+
+### From Indexer Directory
+
+```bash
+cd packages/indexer
+pnpm install
+pnpm run build
+```
+
+## Environment Variables
+
+### Required Variables
+
+#### Database Configuration
+
+- **`DATABASE_URL`**: PostgreSQL connection string
+ - Format: `postgresql://user:password@host:5432/database`
+ - Example: `postgresql://castquest:secret@db.example.com:5432/castquest_indexer`
+ - Required for: Storing indexed data, transaction history
+
+- **`REDIS_URL`**: Redis connection string
+ - Format: `redis://host:port` or `redis://user:password@host:port`
+ - Example: `redis://localhost:6379`
+ - Required for: Caching, rate limiting, job queue
+
+#### RPC Endpoints
+
+- **`BASE_RPC_URL`**: Base network RPC endpoint
+ - Example: `https://mainnet.base.org`
+ - Required: Yes (primary chain)
+ - Rate limit consideration: 10 requests/second recommended
+
+- **`ETHEREUM_RPC_URL`**: Ethereum mainnet RPC endpoint
+ - Example: `https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY`
+ - Required: For cross-chain operations
+ - Provider options: Alchemy, Infura, QuickNode
+
+- **`ARBITRUM_RPC_URL`**: Arbitrum RPC endpoint (optional)
+ - Example: `https://arb-mainnet.g.alchemy.com/v2/YOUR-API-KEY`
+ - Required: If indexing Arbitrum chain
+
+- **`OPTIMISM_RPC_URL`**: Optimism RPC endpoint (optional)
+ - Example: `https://opt-mainnet.g.alchemy.com/v2/YOUR-API-KEY`
+ - Required: If indexing Optimism chain
+
+- **`POLYGON_RPC_URL`**: Polygon RPC endpoint (optional)
+ - Example: `https://polygon-mainnet.g.alchemy.com/v2/YOUR-API-KEY`
+ - Required: If indexing Polygon chain
+
+### Optional Variables
+
+- **`INDEXER_PORT`**: HTTP API port (default: 8080)
+- **`INDEXER_START_BLOCK`**: Block number to start indexing from
+ - Default: Latest block
+ - Set to specific block for re-indexing
+
+- **`INDEXER_BATCH_SIZE`**: Number of blocks to process per batch (default: 100)
+- **`INDEXER_CONCURRENCY`**: Concurrent indexing tasks (default: 5)
+- **`INDEXER_LOG_LEVEL`**: Logging verbosity
+ - Options: 'debug', 'info', 'warn', 'error'
+ - Default: 'info'
+
+- **`INDEXER_ENABLE_METRICS`**: Enable Prometheus metrics (default: true)
+- **`INDEXER_METRICS_PORT`**: Metrics endpoint port (default: 9090)
+
+### Example `.env` file
+
+```bash
+# Database
+DATABASE_URL=postgresql://castquest:password@localhost:5432/castquest_indexer
+REDIS_URL=redis://localhost:6379
+
+# RPC Endpoints (Required)
+BASE_RPC_URL=https://mainnet.base.org
+ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY
+
+# RPC Endpoints (Optional - for multi-chain)
+ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR-API-KEY
+OPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/YOUR-API-KEY
+POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR-API-KEY
+
+# Indexer Configuration
+INDEXER_PORT=8080
+INDEXER_START_BLOCK=latest
+INDEXER_BATCH_SIZE=100
+INDEXER_CONCURRENCY=5
+INDEXER_LOG_LEVEL=info
+INDEXER_ENABLE_METRICS=true
+INDEXER_METRICS_PORT=9090
+```
+
+## Database Setup
+
+### PostgreSQL Schema
+
+Initialize the database schema:
+
+```bash
+# Connect to PostgreSQL
+psql $DATABASE_URL
+
+# Create database (if not exists)
+CREATE DATABASE castquest_indexer;
+
+# Run migrations (from repository root)
+pnpm --filter @castquest/indexer run migrate
+```
+
+### Schema Tables
+
+The indexer creates the following tables:
+
+- **`blocks`**: Indexed block data
+- **`transactions`**: Transaction records
+- **`events`**: Smart contract events
+- **`buybacks`**: Buyback operations
+- **`social_activity`**: Social interactions
+- **`sync_status`**: Indexing progress per chain
+
+### Database Indexes
+
+Ensure proper indexes for performance:
+
+```sql
+CREATE INDEX idx_events_block_number ON events(block_number);
+CREATE INDEX idx_events_contract ON events(contract_address);
+CREATE INDEX idx_events_timestamp ON events(timestamp);
+CREATE INDEX idx_transactions_hash ON transactions(transaction_hash);
+```
+
+## Build & Development
+
+### Building
+
+```bash
+# From repository root
+pnpm --filter @castquest/indexer build
+
+# From indexer directory
+pnpm run build
+```
+
+**Build Output:** `packages/indexer/dist/` (compiled JavaScript)
+
+### Running in Development
+
+```bash
+# Watch mode with auto-reload
+pnpm --filter @castquest/indexer dev
+
+# Or from indexer directory
+pnpm run dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm --filter @castquest/indexer test
+
+# Type check
+pnpm --filter @castquest/indexer typecheck
+```
+
+### Running in Production
+
+```bash
+# Start indexer
+pnpm --filter @castquest/indexer start
+
+# Or directly
+node packages/indexer/dist/index.js
+```
+
+## Deployment
+
+### Docker Deployment
+
+Build and run with Docker:
+
+```dockerfile
+# infra/docker/Dockerfile.indexer
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY packages/indexer/package.json ./
+COPY packages/indexer/dist ./dist
+
+RUN npm install --production
+
+EXPOSE 8080 9090
+
+CMD ["node", "dist/index.js"]
+```
+
+```bash
+# Build
+docker build -t castquest-indexer:3.0.0 -f infra/docker/Dockerfile.indexer .
+
+# Run
+docker run -d \
+ --name castquest-indexer \
+ -p 8080:8080 \
+ -p 9090:9090 \
+ --env-file .env \
+ castquest-indexer:3.0.0
+```
+
+### Docker Compose
+
+Run indexer with dependencies:
+
+```yaml
+# infra/docker-compose.yml
+services:
+ indexer:
+ build:
+ context: .
+ dockerfile: infra/docker/Dockerfile.indexer
+ ports:
+ - "8080:8080"
+ - "9090:9090"
+ environment:
+ - DATABASE_URL=postgresql://postgres:password@postgres:5432/castquest
+ - REDIS_URL=redis://redis:6379
+ - BASE_RPC_URL=${BASE_RPC_URL}
+ depends_on:
+ - postgres
+ - redis
+
+ postgres:
+ image: postgres:15-alpine
+ environment:
+ POSTGRES_PASSWORD: password
+ POSTGRES_DB: castquest
+ volumes:
+ - postgres-data:/var/lib/postgresql/data
+
+ redis:
+ image: redis:7-alpine
+ volumes:
+ - redis-data:/data
+```
+
+### Kubernetes Deployment
+
+```bash
+# Deploy to staging
+kubectl apply -f infra/k8s/staging/indexer-deployment.yaml
+
+# Deploy to production
+kubectl apply -f infra/k8s/production/indexer-deployment.yaml
+
+# Check status
+kubectl get pods -l app=castquest-indexer
+kubectl logs -f deployment/castquest-indexer
+```
+
+### Health Checks
+
+The indexer exposes health endpoints:
+
+```bash
+# Overall health
+curl http://localhost:8080/health
+
+# Liveness probe
+curl http://localhost:8080/health/live
+
+# Readiness probe (checks DB and RPC)
+curl http://localhost:8080/health/ready
+```
+
+Response example:
+```json
+{
+ "status": "healthy",
+ "database": "connected",
+ "redis": "connected",
+ "chains": {
+ "base": {
+ "status": "synced",
+ "lastBlock": 12345678,
+ "lag": 2
+ },
+ "ethereum": {
+ "status": "syncing",
+ "lastBlock": 18900000,
+ "lag": 145
+ }
+ }
+}
+```
+
+## Runtime Operations
+
+### Starting from Specific Block
+
+To re-index from a specific block:
+
+```bash
+INDEXER_START_BLOCK=10000000 pnpm --filter @castquest/indexer start
+```
+
+### Indexing Status
+
+Check indexing progress:
+
+```bash
+curl http://localhost:8080/api/v1/status
+```
+
+Response:
+```json
+{
+ "chains": {
+ "base": {
+ "latestBlock": 12345678,
+ "indexedBlock": 12345676,
+ "blocksPerSecond": 5.2,
+ "estimatedCompletion": "2026-01-20T10:00:00Z"
+ }
+ }
+}
+```
+
+### Backfilling Data
+
+To backfill missing blocks:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/backfill \
+ -H "Content-Type: application/json" \
+ -d '{"chain": "base", "fromBlock": 10000000, "toBlock": 10001000}'
+```
+
+## Security
+
+### RPC Security
+
+- **Never expose RPC URLs** in public repositories
+- Use environment variables or secrets manager
+- Rotate API keys quarterly
+- Monitor RPC usage and rate limits
+- Use authenticated RPC endpoints
+
+### Database Security
+
+- **Strong passwords**: 16+ characters, mixed case, special chars
+- **SSL/TLS connections**: Add `?sslmode=require` to DATABASE_URL
+- **Restricted access**: Limit database access to indexer IP
+- **Regular backups**: Daily automated backups
+- **Encryption at rest**: Enable PostgreSQL encryption
+
+### API Security
+
+- **Rate limiting**: 100 requests/min per IP (configurable)
+- **API authentication**: Optional API key for sensitive endpoints
+- **CORS**: Restrict origins in production
+- **Input validation**: Sanitize all query parameters
+
+### Network Security
+
+- **Firewall rules**: Allow only necessary ports
+ - 8080 (API) - restricted to application servers
+ - 9090 (Metrics) - restricted to monitoring systems
+ - 5432 (PostgreSQL) - restricted to indexer
+ - 6379 (Redis) - restricted to indexer
+
+- **VPC isolation**: Deploy in private VPC
+- **TLS encryption**: Use HTTPS for API endpoints
+
+## Monitoring & Observability
+
+### Metrics
+
+Prometheus metrics available at `http://localhost:9090/metrics`:
+
+```
+# Indexing progress
+indexer_blocks_processed_total{chain="base"}
+indexer_events_indexed_total{chain="base",event="Transfer"}
+
+# Performance
+indexer_block_processing_duration_seconds{chain="base"}
+indexer_batch_processing_duration_seconds{chain="base"}
+
+# Errors
+indexer_errors_total{chain="base",type="rpc_error"}
+indexer_reorg_detected_total{chain="base"}
+
+# Database
+indexer_db_queries_total
+indexer_db_query_duration_seconds
+
+# RPC
+indexer_rpc_requests_total{chain="base",method="eth_getLogs"}
+indexer_rpc_errors_total{chain="base"}
+```
+
+### Logging
+
+Structured JSON logging:
+
+```json
+{
+ "level": "info",
+ "timestamp": "2026-01-20T06:00:00.000Z",
+ "service": "indexer",
+ "chain": "base",
+ "message": "Block processed",
+ "blockNumber": 12345678,
+ "eventCount": 42,
+ "duration": 1.234
+}
+```
+
+### Alerts
+
+Set up alerts for:
+- Indexing lag > 100 blocks for 10 minutes
+- RPC error rate > 5% for 5 minutes
+- Database connection failures
+- Memory usage > 85%
+- Disk space < 10GB
+
+## Troubleshooting
+
+### Common Issues
+
+**"Cannot connect to database"**
+- Verify DATABASE_URL is correct
+- Check PostgreSQL is running: `pg_isready -h localhost`
+- Ensure firewall allows connection
+- Check credentials
+
+**"RPC request failed"**
+- Verify RPC URL is correct and accessible
+- Check API key is valid
+- Verify rate limits not exceeded
+- Try alternative RPC provider
+
+**"Indexing lag increasing"**
+- Increase INDEXER_CONCURRENCY
+- Increase INDEXER_BATCH_SIZE
+- Use faster RPC endpoint
+- Scale horizontally (multiple indexers)
+
+**"Database full"**
+- Increase storage capacity
+- Archive old data
+- Enable PostgreSQL auto-vacuum
+- Implement data retention policy
+
+**"Memory usage high"**
+- Reduce INDEXER_BATCH_SIZE
+- Reduce INDEXER_CONCURRENCY
+- Increase container memory limit
+- Check for memory leaks
+
+### Performance Tuning
+
+For high-throughput scenarios:
+
+```bash
+# Increase batch size
+INDEXER_BATCH_SIZE=500
+
+# Increase concurrency
+INDEXER_CONCURRENCY=10
+
+# Use connection pooling
+DATABASE_POOL_SIZE=20
+```
+
+## Next Steps
+
+- [Indexer Architecture](/overview/architecture#indexer) - Deep dive
+- [Data Model](/overview/data-model) - Database schema
+- [API Reference](/reference/api-reference#indexer) - API documentation
+- [Multi-chain Architecture](/overview/multi-chain-architecture) - Cross-chain indexing
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/overview/web-app-setup.mdx b/docs-site/overview/web-app-setup.mdx
new file mode 100644
index 0000000..9ea0add
--- /dev/null
+++ b/docs-site/overview/web-app-setup.mdx
@@ -0,0 +1,579 @@
+---
+title: "Web Application Setup & Deployment"
+section: "overview"
+slug: "web-app-setup"
+tags: ["web", "setup", "nextjs", "deployment"]
+weight: 15
+navOrder: 15
+---
+
+# Web Application Setup & Deployment
+
+> CASTQUEST V3 — Next.js Web Application Configuration Guide
+
+## Overview
+
+The CASTQUEST web application (`@castquest/web`) is a Next.js-based frontend that provides the user interface for interacting with the CASTQUEST protocol, including frames, quests, mints, marketplace, and profile management.
+
+**Code Path:** `apps/web/`
+
+## Architecture
+
+### Technology Stack
+
+- **Framework**: Next.js 14.0.0 (App Router)
+- **React**: 18.2.0
+- **TypeScript**: 5.0+
+- **Styling**: Tailwind CSS
+- **UI Components**: shadcn/ui
+- **State Management**: React Context + Hooks
+- **Web3**: ethers.js, viem, WalletConnect
+
+### Application Structure
+
+```
+apps/web/
+├── app/ - Next.js app router pages
+│ ├── api/ - API routes
+│ ├── frames/ - Farcaster frames
+│ ├── quests/ - Quest management
+│ ├── marketplace/ - Marketplace UI
+│ └── profile/ - User profiles
+├── components/ - React components
+├── public/ - Static assets
+├── next.config.mjs - Next.js configuration
+└── package.json - Dependencies
+```
+
+## Prerequisites
+
+- **Node.js**: >= 18.18.0
+- **pnpm**: >= 8.0.0 (package manager)
+- **PostgreSQL**: >= 13 (for session/user data)
+- **Redis**: >= 6 (for caching)
+
+## Installation
+
+### From Repository Root
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build web app
+pnpm --filter @castquest/web build
+```
+
+### From Web Directory
+
+```bash
+cd apps/web
+pnpm install
+pnpm run build
+```
+
+## Environment Variables
+
+### Required Variables
+
+#### Application URLs
+
+- **`NEXT_PUBLIC_APP_URL`**: Public-facing application URL
+ - Example: `https://castquest.io` (production)
+ - Example: `http://localhost:3000` (development)
+ - Used for: OAuth callbacks, canonical URLs
+
+- **`NEXT_PUBLIC_API_URL`**: Backend API endpoint
+ - Example: `https://api.castquest.io`
+ - Used for: API requests from client-side code
+
+- **`NEXT_PUBLIC_WS_URL`**: WebSocket URL for real-time updates
+ - Example: `wss://ws.castquest.io`
+ - Used for: Live notifications, chat
+
+#### Database
+
+- **`DATABASE_URL`**: PostgreSQL connection string
+ - Format: `postgresql://user:password@host:5432/database`
+ - Example: `postgresql://castquest:secret@localhost:5432/castquest_web`
+ - Used for: User sessions, preferences, cached data
+
+- **`DATABASE_POOL_SIZE`**: Connection pool size (default: 20)
+- **`DATABASE_SSL`**: Enable SSL (default: true in production)
+
+#### Session & Authentication
+
+- **`SESSION_SECRET`**: Secret for session encryption
+ - Generate: `openssl rand -base64 32`
+ - Example: `your-session-secret-replace-in-production`
+ - CRITICAL: Keep secret, rotate regularly
+
+- **`NEXTAUTH_URL`**: NextAuth canonical URL
+ - Should match `NEXT_PUBLIC_APP_URL`
+ - Example: `https://castquest.io`
+
+- **`NEXTAUTH_SECRET`**: NextAuth encryption secret
+ - Generate: `openssl rand -base64 32`
+ - Used for: JWT signing, session encryption
+
+- **`JWT_SECRET`**: JWT token secret
+ - Generate: `openssl rand -base64 32`
+ - Used for: API authentication tokens
+
+- **`JWT_EXPIRY`**: JWT token expiry (default: 7d)
+
+#### Blockchain Configuration
+
+- **`NEXT_PUBLIC_DEFAULT_CHAIN_ID`**: Default chain ID
+ - Example: `8453` (Base mainnet)
+ - Options: 1 (Ethereum), 8453 (Base), 42161 (Arbitrum)
+
+- **`NEXT_PUBLIC_SUPPORTED_CHAINS`**: Supported chain IDs (comma-separated)
+ - Example: `1,8453,42161,10,137`
+
+#### Contract Addresses
+
+- **`NEXT_PUBLIC_CAST_TOKEN_ADDRESS`**: CAST token contract
+- **`NEXT_PUBLIC_QUEST_TOKEN_ADDRESS`**: QUEST token contract
+- **`NEXT_PUBLIC_MARKETPLACE_ADDRESS`**: Marketplace contract
+- **`NEXT_PUBLIC_AUCTION_HOUSE_ADDRESS`**: Auction contract
+
+Update these after contract deployment (see Contracts Setup).
+
+#### External Services
+
+- **`WALLETCONNECT_PROJECT_ID`**: WalletConnect project ID
+ - Obtain from: https://cloud.walletconnect.com/
+ - Required for: Wallet connection UI
+
+- **`FARCASTER_API_KEY`**: Farcaster API key
+ - Required for: Frame integration
+ - Obtain from: https://www.farcaster.xyz/
+
+- **`FARCASTER_HUB_URL`**: Farcaster hub URL
+ - Default: `https://hub.farcaster.xyz`
+
+### Optional Variables
+
+#### Storage
+
+- **`AWS_REGION`**: AWS region (default: us-east-1)
+- **`AWS_ACCESS_KEY_ID`**: AWS access key
+- **`AWS_SECRET_ACCESS_KEY`**: AWS secret key
+- **`AWS_S3_BUCKET_NAME`**: S3 bucket for uploads
+- **`AWS_CLOUDFRONT_DISTRIBUTION_ID`**: CloudFront distribution
+
+#### IPFS
+
+- **`PINATA_API_KEY`**: Pinata API key
+- **`PINATA_SECRET_KEY`**: Pinata secret
+- **`IPFS_GATEWAY_URL`**: IPFS gateway URL
+
+#### Monitoring
+
+- **`SENTRY_DSN`**: Sentry error tracking DSN
+- **`SENTRY_ENV`**: Environment name (production, staging)
+- **`SENTRY_TRACES_SAMPLE_RATE`**: Sample rate (0.0-1.0)
+
+#### Performance
+
+- **`NODE_ENV`**: Environment (production, development)
+- **`LOG_LEVEL`**: Logging level (debug, info, warn, error)
+- **`CACHE_TTL`**: Cache TTL in seconds (default: 3600)
+
+### Example `.env.local` (Development)
+
+```bash
+# Application
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:3000/api
+NEXT_PUBLIC_WS_URL=ws://localhost:3000
+
+# Database
+DATABASE_URL=postgresql://postgres:password@localhost:5432/castquest_dev
+DATABASE_SSL=false
+
+# Authentication
+SESSION_SECRET=your-session-secret-replace-in-production
+NEXTAUTH_URL=http://localhost:3000
+NEXTAUTH_SECRET=your-nextauth-secret-replace-in-production
+JWT_SECRET=your-jwt-secret-replace-in-production
+
+# Blockchain
+NEXT_PUBLIC_DEFAULT_CHAIN_ID=8453
+NEXT_PUBLIC_SUPPORTED_CHAINS=1,8453
+
+# WalletConnect
+WALLETCONNECT_PROJECT_ID=your_project_id_here
+
+# Farcaster
+FARCASTER_API_KEY=your_farcaster_key_here
+FARCASTER_HUB_URL=https://hub.farcaster.xyz
+```
+
+### Example `.env.production`
+
+See `.env.production.template` in repository root for complete production configuration.
+
+## Build & Development
+
+### Development Mode
+
+Start development server with hot reload:
+
+```bash
+# From repository root
+pnpm --filter @castquest/web dev
+
+# From web directory
+pnpm run dev
+
+# Access at http://localhost:3000
+```
+
+Features in development mode:
+- Hot module replacement (HMR)
+- Fast refresh
+- Detailed error messages
+- Source maps enabled
+
+### Production Build
+
+Build optimized production bundle:
+
+```bash
+# From repository root
+pnpm --filter @castquest/web build
+
+# From web directory
+pnpm run build
+```
+
+Build output:
+- `.next/` - Compiled application
+- `.next/static/` - Static assets (CSS, JS)
+- `.next/server/` - Server-side code
+
+Build configuration (`next.config.mjs`):
+- Output: Standalone (for Docker)
+- Image optimization: Enabled
+- Compression: Enabled
+- Bundle analyzer: Available via `ANALYZE=true`
+
+### Type Checking
+
+Run TypeScript type checks:
+
+```bash
+pnpm --filter @castquest/web typecheck
+```
+
+### Linting
+
+Run ESLint checks:
+
+```bash
+pnpm --filter @castquest/web lint
+```
+
+### Testing
+
+```bash
+# Run tests (when available)
+pnpm --filter @castquest/web test
+```
+
+## Deployment
+
+### Vercel Deployment (Recommended)
+
+The easiest deployment option for Next.js:
+
+1. **Connect Repository**: Link GitHub repo to Vercel
+2. **Configure Environment**: Add environment variables in Vercel dashboard
+3. **Deploy**: Automatic deployments on push to main
+
+```bash
+# Deploy via Vercel CLI
+vercel --prod
+
+# Set environment variables
+vercel env add NEXT_PUBLIC_APP_URL
+vercel env add DATABASE_URL
+```
+
+### Docker Deployment
+
+Build and run with Docker:
+
+```dockerfile
+# infra/docker/Dockerfile.web
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+COPY . .
+RUN corepack enable && pnpm install
+RUN pnpm --filter @castquest/web build
+
+FROM node:18-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY --from=builder /app/apps/web/.next/standalone ./
+COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
+COPY --from=builder /app/apps/web/public ./apps/web/public
+
+EXPOSE 3000
+CMD ["node", "apps/web/server.js"]
+```
+
+Build and run:
+
+```bash
+# Build image
+docker build -t castquest-web:3.0.0 -f infra/docker/Dockerfile.web .
+
+# Run container
+docker run -d \
+ --name castquest-web \
+ -p 3000:3000 \
+ --env-file .env.production \
+ castquest-web:3.0.0
+```
+
+### Kubernetes Deployment
+
+Deploy to Kubernetes:
+
+```bash
+# Apply staging deployment
+kubectl apply -f infra/k8s/staging/web-deployment.yaml
+
+# Apply production deployment
+kubectl apply -f infra/k8s/production/web-deployment.yaml
+
+# Check status
+kubectl get pods -l app=castquest-web
+kubectl logs -f deployment/castquest-web
+```
+
+### Static Export (Optional)
+
+For static hosting (CloudFront, Netlify):
+
+```bash
+# Configure static export in next.config.mjs
+# output: 'export'
+
+# Build static files
+pnpm run build
+
+# Output in: apps/web/out/
+```
+
+**Note**: Static export has limitations (no API routes, no SSR).
+
+## Performance Optimization
+
+### Image Optimization
+
+Next.js Image component:
+```typescript
+import Image from 'next/image';
+
+
+```
+
+### Code Splitting
+
+Automatic code splitting by Next.js. Lazy load heavy components:
+
+```typescript
+import dynamic from 'next/dynamic';
+
+const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
+ loading: () => Loading...
,
+});
+```
+
+### Caching Strategy
+
+Configure caching in `next.config.mjs`:
+```javascript
+export default {
+ cacheHandler: './cache-handler.js',
+ cacheMaxMemorySize: 50 * 1024 * 1024, // 50MB
+};
+```
+
+### Bundle Analysis
+
+Analyze bundle size:
+
+```bash
+ANALYZE=true pnpm run build
+```
+
+Opens interactive bundle analyzer in browser.
+
+## Security
+
+### Environment Variables
+
+- **Never commit** `.env.local` or `.env.production`
+- Use **NEXT_PUBLIC_** prefix only for client-safe variables
+- Store secrets in **secrets manager** (AWS Secrets Manager, Vercel)
+- Rotate secrets every 90 days
+
+### Authentication
+
+- Use **NextAuth.js** for authentication
+- Enable **CSRF protection** (enabled by default)
+- Implement **rate limiting** on API routes
+- Use **httpOnly cookies** for session tokens
+
+### API Routes
+
+Secure API routes:
+
+```typescript
+// apps/web/app/api/example/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getServerSession } from 'next-auth';
+
+export async function GET(req: NextRequest) {
+ // Verify authentication
+ const session = await getServerSession();
+ if (!session) {
+ return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+ }
+
+ // Rate limiting (implement with redis)
+ // Input validation
+ // ...
+}
+```
+
+### Content Security Policy
+
+Configure CSP headers in `next.config.mjs`:
+
+```javascript
+const securityHeaders = [
+ {
+ key: 'Content-Security-Policy',
+ value: "default-src 'self'; script-src 'self' 'unsafe-eval'; ..."
+ }
+];
+```
+
+### HTTPS
+
+Always use HTTPS in production:
+- Redirect HTTP to HTTPS
+- Set secure cookie flags
+- Enable HSTS headers
+
+## Monitoring
+
+### Health Checks
+
+Health endpoint: `apps/web/app/api/health/route.ts`
+
+```bash
+curl https://castquest.io/api/health
+```
+
+Response:
+```json
+{
+ "status": "healthy",
+ "database": "connected",
+ "redis": "connected",
+ "uptime": 86400
+}
+```
+
+### Error Tracking
+
+Configure Sentry:
+
+```typescript
+// apps/web/instrumentation.ts
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({
+ dsn: process.env.SENTRY_DSN,
+ environment: process.env.SENTRY_ENV,
+ tracesSampleRate: 0.1,
+});
+```
+
+### Performance Monitoring
+
+- **Core Web Vitals**: Monitored by default
+- **Vercel Analytics**: Enable in Vercel dashboard
+- **Custom metrics**: Use `performance.measure()`
+
+### Logging
+
+Structured logging:
+
+```typescript
+const logger = {
+ info: (msg: string, meta?: object) => {
+ console.log(JSON.stringify({ level: 'info', message: msg, ...meta }));
+ },
+ error: (msg: string, error?: Error) => {
+ console.error(JSON.stringify({ level: 'error', message: msg, error }));
+ }
+};
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"Error: Cannot find module"**
+- Run `pnpm install`
+- Delete `.next` folder: `rm -rf .next`
+- Rebuild: `pnpm run build`
+
+**"Database connection failed"**
+- Verify `DATABASE_URL` is correct
+- Check PostgreSQL is running
+- Ensure firewall allows connection
+
+**"NEXTAUTH_URL mismatch"**
+- Ensure `NEXTAUTH_URL` matches actual domain
+- Include protocol (https://)
+- No trailing slash
+
+**"Out of memory during build"**
+- Increase Node.js memory: `NODE_OPTIONS=--max-old-space-size=4096`
+- Reduce concurrent workers
+- Use swap space
+
+**"Static export failed"**
+- Remove dynamic features (API routes, ISR)
+- Or use server deployment instead
+
+## Next Steps
+
+- [Frames Setup](/frames/setup) - Farcaster frame integration
+- [Quests Setup](/quests/setup) - Quest configuration
+- [Marketplace](/marketplace/) - Marketplace features
+- [API Reference](/reference/api-reference) - API documentation
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/protocol/contracts-setup.mdx b/docs-site/protocol/contracts-setup.mdx
new file mode 100644
index 0000000..90ef17a
--- /dev/null
+++ b/docs-site/protocol/contracts-setup.mdx
@@ -0,0 +1,552 @@
+---
+title: "Smart Contracts Setup & Deployment"
+section: "protocol"
+slug: "contracts-setup"
+tags: ["contracts", "deployment", "blockchain"]
+weight: 10
+navOrder: 10
+---
+
+# Smart Contracts Setup & Deployment
+
+> CASTQUEST V3 — Smart Contract Development & Deployment Guide
+
+## Overview
+
+The CASTQUEST smart contracts (`@castquest/contracts`) implement the core protocol logic on EVM-compatible blockchains. The contracts are organized into modules for core functionality, economy, governance, L3, marketplace, and social features.
+
+**Code Path:** `packages/contracts/`
+
+## Contract Structure
+
+### Contract Modules
+
+The contracts are organized by functionality (see `packages/contracts/`):
+
+```
+packages/contracts/
+├── core/ - Core protocol contracts
+├── economy/ - Token economics & treasury
+├── governance/ - DAO governance contracts
+├── l3/ - Layer 3 contracts
+├── marketplace/ - Marketplace & trading
+├── social/ - Social features (frames, profiles)
+├── scripts/ - Deployment scripts
+└── test/ - Contract tests
+```
+
+### Key Contracts
+
+**Core:**
+- `CastToken.sol` - CAST governance token
+- `QuestToken.sol` - QUEST reward token
+- `ProfileNFT.sol` - Tokenized user profiles
+
+**Economy:**
+- `Treasury.sol` - Protocol treasury
+- `BuybackEngine.sol` - Token buyback mechanism
+- `FeeCollector.sol` - Fee collection and distribution
+
+**Governance:**
+- `CastDAO.sol` - Main DAO governance
+- `Timelock.sol` - Governance timelock
+- `GovernorBravo.sol` - Voting implementation
+
+**Marketplace:**
+- `Marketplace.sol` - Core marketplace logic
+- `Auction.sol` - Auction mechanism
+- `Royalties.sol` - Royalty distribution
+
+## Prerequisites
+
+- **Node.js**: >= 18.18.0
+- **Hardhat**: Installed via package dependencies
+- **TypeScript**: >= 5.3.3
+- **Solidity**: 0.8.20+ (configured in hardhat.config.ts)
+- **Wallet**: Private key for deployment
+
+## Installation
+
+### From Repository Root
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build contracts
+pnpm --filter @castquest/contracts build
+```
+
+### From Contracts Directory
+
+```bash
+cd packages/contracts
+pnpm install
+pnpm run build
+```
+
+## Environment Variables
+
+### Required for Deployment
+
+#### Deployer Configuration
+
+- **`DEPLOYER_PRIVATE_KEY`**: Private key for contract deployment
+ - Format: 64-character hex string (without 0x prefix)
+ - Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+ - Security: NEVER commit to git, use secrets manager
+ - Ensure sufficient ETH/gas tokens for deployment
+
+#### RPC Endpoints
+
+- **`BASE_RPC_URL`**: Base network RPC endpoint
+ - Example: `https://mainnet.base.org`
+ - Required for: Base mainnet deployment
+ - Alternative: `https://base-mainnet.g.alchemy.com/v2/YOUR-KEY`
+
+- **`BASE_SEPOLIA_RPC_URL`**: Base Sepolia testnet RPC
+ - Example: `https://sepolia.base.org`
+ - Required for: Testnet deployment
+ - Get testnet ETH: https://sepoliafaucet.com/
+
+- **`ETHEREUM_RPC_URL`**: Ethereum mainnet RPC endpoint
+ - Example: `https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY`
+ - Required for: Ethereum deployment
+ - Providers: Alchemy, Infura, QuickNode
+
+#### Block Explorer API Keys
+
+- **`BASESCAN_API_KEY`**: Basescan API key
+ - Obtain from: https://basescan.org/myapikey
+ - Required for: Contract verification on Base
+ - Example: `ABC123DEF456GHI789`
+
+- **`ETHERSCAN_API_KEY`**: Etherscan API key
+ - Obtain from: https://etherscan.io/myapikey
+ - Required for: Contract verification on Ethereum
+ - Example: `XYZ789ABC123DEF456`
+
+### Optional Variables
+
+- **`GAS_REPORTER_ENABLED`**: Enable gas reporting in tests (default: false)
+- **`COINMARKETCAP_API_KEY`**: For USD gas cost estimates
+- **`HARDHAT_NETWORK`**: Network to use (default: hardhat)
+
+### Example `.env` file
+
+```bash
+# CRITICAL: NEVER commit this file to git
+# Add .env to .gitignore
+
+# Deployer (KEEP SECRET! NEVER USE IN PRODUCTION WITHOUT HARDWARE WALLET)
+DEPLOYER_PRIVATE_KEY=your_private_key_here
+
+# RPC Endpoints
+BASE_RPC_URL=https://mainnet.base.org
+BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY
+
+# Block Explorers
+BASESCAN_API_KEY=YOUR_BASESCAN_API_KEY
+ETHERSCAN_API_KEY=YOUR_ETHERSCAN_API_KEY
+
+# Optional
+GAS_REPORTER_ENABLED=false
+COINMARKETCAP_API_KEY=your_cmc_api_key
+```
+
+## Build & Compilation
+
+### Compile Contracts
+
+```bash
+# From repository root
+pnpm --filter @castquest/contracts build
+
+# From contracts directory
+pnpm run build
+
+# Clean and rebuild
+pnpm run clean && pnpm run build
+```
+
+**Build Output:**
+- `artifacts/` - Compiled contract artifacts (ABI, bytecode)
+- `typechain-types/` - TypeScript types for contracts
+- `cache/` - Hardhat cache (can be deleted)
+
+### Compilation Options
+
+Configured in `packages/contracts/hardhat.config.ts`:
+- Solidity version: 0.8.20
+- Optimizer: Enabled (200 runs for mainnet)
+- EVM version: paris
+- Metadata: Full source code included
+
+## Testing
+
+### Run Tests
+
+```bash
+# Run all tests
+pnpm --filter @castquest/contracts test
+
+# Run specific test file
+pnpm run test test/CastToken.test.ts
+
+# Run with gas reporting
+GAS_REPORTER_ENABLED=true pnpm run test
+
+# Run with coverage
+pnpm run test:coverage
+```
+
+### Test Coverage
+
+Generate coverage report:
+
+```bash
+pnpm --filter @castquest/contracts test:coverage
+```
+
+View report: `packages/contracts/coverage/index.html`
+
+### Test Networks
+
+Hardhat provides built-in networks:
+- `hardhat` - Local ephemeral network
+- `localhost` - Persistent local network (requires `npx hardhat node`)
+
+## Deployment
+
+### Pre-Deployment Checklist
+
+Before deploying to mainnet:
+
+- [ ] All tests passing
+- [ ] Security audit completed
+- [ ] Gas optimization verified
+- [ ] Deployment script tested on testnet
+- [ ] Environment variables configured
+- [ ] Deployer wallet funded with sufficient ETH
+- [ ] Multisig setup for contract ownership
+- [ ] Emergency pause mechanism tested
+
+### Deploy to Localhost
+
+For local development:
+
+```bash
+# Terminal 1: Start local node
+npx hardhat node
+
+# Terminal 2: Deploy contracts
+pnpm --filter @castquest/contracts deploy:localhost
+```
+
+### Deploy to Base Testnet
+
+Test deployment on Base Sepolia:
+
+```bash
+pnpm --filter @castquest/contracts deploy:base-testnet
+
+# Or explicitly
+npx hardhat run scripts/deploy.ts --network baseSepolia
+```
+
+Verify deployment:
+```bash
+npx hardhat verify --network baseSepolia CONTRACT_ADDRESS "Constructor Arg 1" "Constructor Arg 2"
+```
+
+### Deploy to Base Mainnet
+
+**WARNING: Mainnet deployment is irreversible. Double-check everything.**
+
+```bash
+# Deploy to Base mainnet
+pnpm --filter @castquest/contracts deploy:base
+
+# Or explicitly
+npx hardhat run scripts/deploy.ts --network base
+```
+
+### Deploy to Ethereum Mainnet
+
+```bash
+# Deploy to Ethereum
+pnpm --filter @castquest/contracts deploy:mainnet
+
+# Or explicitly
+npx hardhat run scripts/deploy.ts --network mainnet
+```
+
+### Deployment Script
+
+The deployment script (`packages/contracts/scripts/deploy.ts`) performs:
+
+1. Validation of deployer account
+2. Network confirmation
+3. Gas price estimation
+4. Contract deployment in order
+5. Contract verification on block explorer
+6. Output of deployed addresses
+7. Save deployment manifest to `deployments/{network}.json`
+
+### Multi-Chain Deployment
+
+For cross-chain deployment:
+
+```bash
+# Deploy to all networks
+./packages/contracts/scripts/deploy-multichain.sh
+
+# Deploys to:
+# - Base mainnet
+# - Ethereum mainnet
+# - Arbitrum (optional)
+# - Optimism (optional)
+```
+
+### Contract Verification
+
+Verify contracts on block explorers:
+
+```bash
+# Verify on Basescan
+npx hardhat verify --network base \
+ CONTRACT_ADDRESS \
+ "Constructor Arg 1" \
+ "Constructor Arg 2"
+
+# Verify on Etherscan
+npx hardhat verify --network mainnet \
+ CONTRACT_ADDRESS \
+ "Constructor Arg 1"
+```
+
+### Post-Deployment
+
+After deployment:
+
+1. **Transfer Ownership**: Transfer contract ownership to multisig
+ ```bash
+ npx hardhat run scripts/transfer-ownership.ts --network base
+ ```
+
+2. **Initialize Contracts**: Call initialization functions
+ ```bash
+ npx hardhat run scripts/initialize.ts --network base
+ ```
+
+3. **Update Frontend**: Update contract addresses in web app config
+
+4. **Update Indexer**: Configure indexer with new contract addresses
+
+5. **Announce**: Publish deployment addresses
+
+## Security
+
+### Private Key Security
+
+**CRITICAL SECURITY PRACTICES:**
+
+- **NEVER hardcode** private keys in code
+- **NEVER commit** `.env` files to git
+- Use **hardware wallets** (Ledger, Trezor) for mainnet
+- Use **multisig wallets** for contract ownership
+- Rotate keys after deployment
+- Use **different keys** for testnet and mainnet
+
+### Using Hardware Wallet
+
+For maximum security, deploy using hardware wallet:
+
+```typescript
+// hardhat.config.ts
+import { HardhatUserConfig } from "hardhat/config";
+import "@nomiclabs/hardhat-ledger";
+
+const config: HardhatUserConfig = {
+ networks: {
+ base: {
+ url: process.env.BASE_RPC_URL,
+ ledgerAccounts: [0] // Use first account on Ledger
+ }
+ }
+};
+```
+
+### Multisig Ownership
+
+Transfer ownership to multisig after deployment:
+
+```typescript
+// Transfer ownership to Gnosis Safe
+await contract.transferOwnership(GNOSIS_SAFE_ADDRESS);
+```
+
+Recommended multisig configuration:
+- 3-of-5 for testnet
+- 5-of-7 for mainnet
+- Include team members and advisors
+
+### Emergency Procedures
+
+Implement emergency pause:
+
+```solidity
+// In contract
+function pause() external onlyOwner {
+ _pause();
+}
+
+function unpause() external onlyOwner {
+ _unpause();
+}
+```
+
+Emergency contacts:
+- Primary: security@castquest.io
+- Backup: PagerDuty alerts
+
+### Audit Requirements
+
+Before mainnet deployment:
+
+1. **Internal Review**: Code review by 2+ engineers
+2. **Automated Analysis**: Slither, Mythril, MythX
+3. **External Audit**: Professional audit firm
+4. **Bug Bounty**: Launch bug bounty program (Immunefi)
+
+### Automated Security Checks
+
+Run security checks:
+
+```bash
+# Solhint linting
+pnpm run lint
+
+# Slither static analysis
+slither packages/contracts
+
+# Mythril analysis
+myth analyze packages/contracts/core/CastToken.sol
+```
+
+### Gas Optimization
+
+Optimize gas costs:
+
+```bash
+# Generate gas report
+GAS_REPORTER_ENABLED=true pnpm run test
+
+# View gas costs
+cat gas-report.txt
+```
+
+Target gas costs:
+- Token transfer: < 50k gas
+- NFT mint: < 100k gas
+- Marketplace listing: < 150k gas
+
+## Monitoring
+
+### On-Chain Monitoring
+
+Monitor deployed contracts:
+
+- **Block Explorer**: https://basescan.org/address/CONTRACT_ADDRESS
+- **Etherscan**: https://etherscan.io/address/CONTRACT_ADDRESS
+- **OpenZeppelin Defender**: Automated monitoring and alerts
+
+### Events
+
+All contracts emit events for important actions:
+
+```solidity
+event Transfer(address indexed from, address indexed to, uint256 value);
+event Approval(address indexed owner, address indexed spender, uint256 value);
+event Paused(address account);
+```
+
+Monitor events via:
+- Indexer service (see Indexer Setup)
+- The Graph subgraph
+- Alchemy/Infura webhooks
+
+### Alerts
+
+Set up alerts for:
+- Large transfers (> $100k)
+- Ownership changes
+- Pause/unpause events
+- Failed transactions
+- Unusual gas consumption
+
+## Upgradeability
+
+CASTQUEST contracts use proxy patterns for upgradeability:
+
+### Transparent Proxy Pattern
+
+```typescript
+// Deploy implementation
+const Implementation = await ethers.getContractFactory("CastToken");
+const implementation = await Implementation.deploy();
+
+// Deploy proxy
+const TransparentUpgradeableProxy = await ethers.getContractFactory("TransparentUpgradeableProxy");
+const proxy = await TransparentUpgradeableProxy.deploy(
+ implementation.address,
+ proxyAdmin.address,
+ initData
+);
+```
+
+### Upgrade Process
+
+1. Deploy new implementation
+2. Test on testnet
+3. Security audit of changes
+4. Propose upgrade to DAO
+5. Execute upgrade via timelock
+
+## Troubleshooting
+
+### Common Issues
+
+**"Insufficient funds for gas"**
+- Ensure deployer has enough ETH
+- Check gas price: `await ethers.provider.getGasPrice()`
+- Fund wallet: https://bridge.base.org/
+
+**"Nonce too low"**
+- Reset account nonce: `npx hardhat clean`
+- Or manually: `--nonce X`
+
+**"Contract verification failed"**
+- Ensure exact compiler settings match
+- Include all constructor arguments
+- Wait 1-2 minutes after deployment
+- Try `--force` flag
+
+**"Transaction underpriced"**
+- Increase gas price in hardhat.config.ts
+- Wait for network congestion to clear
+
+## Next Steps
+
+- [Protocol Architecture](/protocol/architecture) - Contract architecture
+- [Governance](/protocol/governance) - DAO governance
+- [Token Economics](/tokens/) - Token details
+- [API Reference](/reference/api-reference) - Contract ABIs
+
+## Support
+
+- **Security Issues**: security@castquest.io (DO NOT disclose publicly)
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/protocol
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/quests/setup.mdx b/docs-site/quests/setup.mdx
new file mode 100644
index 0000000..1f8a7ab
--- /dev/null
+++ b/docs-site/quests/setup.mdx
@@ -0,0 +1,304 @@
+---
+title: "Quests Setup & Configuration"
+section: "quests"
+slug: "setup"
+tags: ["quests", "setup", "gamification"]
+weight: 1
+navOrder: 1
+---
+
+# Quests Setup & Configuration
+
+> CASTQUEST V3 — Quest System Configuration Guide
+
+## Overview
+
+Quests are gamified challenges that users complete to earn rewards. The quest system is integrated into the web application and supports various quest types, verification methods, and reward mechanisms.
+
+**Code Path:** `apps/web/app/quests/` (part of web application)
+
+## Architecture
+
+### Quest System Components
+
+- **Quest Engine**: Core logic for quest lifecycle
+- **Verification**: On-chain and off-chain verification
+- **Rewards**: Token distribution and NFT minting
+- **Tracking**: Progress monitoring and analytics
+
+### Quest Types
+
+- **Social Quests**: Follow, share, engage on social platforms
+- **On-chain Quests**: Complete blockchain transactions
+- **Content Quests**: Create and submit content
+- **Engagement Quests**: Platform interaction milestones
+- **Custom Quests**: Developer-defined challenges
+
+## Prerequisites
+
+- Web application setup (see Web App Setup)
+- Smart contracts deployed (for on-chain quests)
+- Database configured (for quest state)
+- Redis configured (for caching)
+
+## Environment Variables
+
+Quests use the same environment configuration as the web application. No additional quest-specific environment variables are required.
+
+### Relevant Variables
+
+From web app configuration:
+
+- **`DATABASE_URL`**: For quest state and progress
+- **`REDIS_URL`**: For caching quest data
+- **`NEXT_PUBLIC_QUEST_TOKEN_ADDRESS`**: Quest token contract address
+- **`NEXT_PUBLIC_DEFAULT_CHAIN_ID`**: Chain for on-chain verification
+
+## Setup Steps
+
+### 1. Database Schema
+
+Initialize quest tables (run migrations from web app):
+
+```bash
+# Run database migrations
+pnpm --filter @castquest/web run migrate
+```
+
+Quest tables:
+- `quests` - Quest definitions
+- `quest_progress` - User progress tracking
+- `quest_completions` - Completed quests
+- `quest_rewards` - Reward distribution
+
+### 2. Configure Quest Types
+
+Quest types are configured in the web app:
+
+```typescript
+// apps/web/app/quests/config.ts
+export const QUEST_TYPES = {
+ SOCIAL: {
+ name: 'Social Quest',
+ verificationMethod: 'api',
+ rewardType: 'token'
+ },
+ ONCHAIN: {
+ name: 'On-chain Quest',
+ verificationMethod: 'blockchain',
+ rewardType: 'nft'
+ },
+ // ... more types
+};
+```
+
+### 3. Set Up Verification
+
+Configure verification services:
+
+```typescript
+// Social verification (Twitter, Farcaster)
+TWITTER_API_KEY=your_twitter_api_key
+FARCASTER_API_KEY=your_farcaster_api_key
+
+// On-chain verification (via indexer)
+INDEXER_URL=http://localhost:8080
+```
+
+## Build & Development
+
+Quests are part of the web application:
+
+```bash
+# Development
+pnpm --filter @castquest/web dev
+
+# Build
+pnpm --filter @castquest/web build
+
+# Test quest routes
+curl http://localhost:3000/api/quests
+```
+
+## Security
+
+### Verification Security
+
+- **Prevent Fraud**: Multiple verification checks
+- **Rate Limiting**: Limit verification attempts
+- **Spam Prevention**: Cooldown periods between completions
+- **Reward Validation**: Verify reward availability before distribution
+
+## Deployment Process
+
+Quests are deployed as part of the web application:
+
+### Steps
+
+1. **Deploy Web App**: Quests deploy with main application
+ ```bash
+ pnpm --filter @castquest/web build
+ pnpm --filter @castquest/web start
+ ```
+
+2. **Initialize Quest Database**: Run migrations
+ ```bash
+ pnpm run db:migrate
+ ```
+
+3. **Configure Quest Rewards**: Set up reward pools
+ ```bash
+ pnpm run quest:fund-pool --amount 10000
+ ```
+
+4. **Activate Quests**: Publish quests to users
+ ```bash
+ pnpm run quest:publish --ids 1,2,3
+ ```
+
+### Production Considerations
+
+- **Reward Pool Monitoring**: Ensure sufficient balance for rewards
+- **Verification Services**: High availability for verification APIs
+- **Database Performance**: Index quest tables for fast queries
+- **Caching**: Cache quest data for better performance
+
+## Security
+
+### Verification Security
+
+- **Prevent Fraud**: Multiple verification checks
+- **Rate Limiting**: Limit verification attempts per user
+- **Spam Prevention**: Cooldown periods between completions
+- **Reward Validation**: Verify reward availability before distribution
+- **Double-claim Prevention**: Check for existing completions
+
+### Quest Creation Security
+
+```typescript
+// Only admins can create quests
+export async function POST(req: NextRequest) {
+ const session = await getServerSession();
+
+ if (!session?.user?.isAdmin) {
+ return NextResponse.json({ error: 'Unauthorized' }, { status: 403 });
+ }
+
+ // Create quest
+}
+```
+
+### Reward Security
+
+- **Authorization**: Only authorized addresses distribute rewards
+- **Balance Checks**: Verify sufficient balance before rewards
+- **Transaction Monitoring**: Track all reward distributions
+- **Audit Trail**: Log all quest completions and rewards
+- **Fraud Detection**: Monitor for suspicious patterns
+
+### Best Practices
+
+- **Validate quest criteria**: Ensure criteria are achievable
+- **Test verification**: Test all verification methods
+- **Monitor completion rates**: Track success/failure rates
+- **Set cooldown periods**: Prevent quest farming
+- **Implement fraud detection**: Monitor for suspicious activity
+- **Audit regularly**: Review quest completions and rewards
+- **Use secure APIs**: Only use trusted verification APIs
+
+## Monitoring
+
+### Quest Metrics
+
+Track key metrics:
+- Quest start rate
+- Completion rate
+- Average completion time
+- Reward distribution
+- Failed verifications
+
+### Performance
+
+Monitor quest system performance:
+- Verification latency
+- Database query performance
+- Reward transaction success rate
+- API response times
+
+## Quest Operations
+
+### Creating Quests
+
+Create quests via admin API:
+
+```typescript
+POST /api/admin/quests
+{
+ "name": "Complete Your First Trade",
+ "description": "Make a trade on the marketplace",
+ "type": "ONCHAIN",
+ "verificationCriteria": {
+ "contractAddress": "0x...",
+ "eventName": "TradeCompleted"
+ },
+ "reward": {
+ "type": "token",
+ "amount": "100"
+ }
+}
+```
+
+### Verifying Completions
+
+Verification flow:
+
+1. User claims quest completion
+2. System checks verification criteria
+3. If valid, marks as complete
+4. Distributes reward
+5. Emits completion event
+
+### Managing Rewards
+
+Configure reward pools:
+
+```bash
+# Fund reward pool
+pnpm run quest:fund-pool --amount 10000
+
+# Check pool balance
+pnpm run quest:pool-balance
+```
+
+## Troubleshooting
+
+**"Verification failed"**
+- Check verification service connectivity
+- Verify user actually completed action
+- Check for API rate limits
+- Review verification logs
+
+**"Reward distribution failed"**
+- Ensure reward pool has sufficient balance
+- Check user wallet is valid
+- Verify transaction gas limits
+- Review blockchain network status
+
+**"Quest not visible"**
+- Check quest is published
+- Verify eligibility criteria
+- Check database connectivity
+- Review user permissions
+
+## Next Steps
+
+- [Quest Types](/quests/quest-types) - Available quest types
+- [Quest Verification](/quests/quest-verification) - Verification methods
+- [Quest Rewards](/quests/quest-rewards) - Reward configuration
+- [Quest API](/reference/api-reference#quests) - API documentation
+
+## Support
+
+- **GitHub**: https://github.com/CastQuest/cast/issues
+- **Docs**: https://docs.castquest.io/quests
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/reference/docs-validation.mdx b/docs-site/reference/docs-validation.mdx
new file mode 100644
index 0000000..f08d88a
--- /dev/null
+++ b/docs-site/reference/docs-validation.mdx
@@ -0,0 +1,398 @@
+---
+title: "Documentation Validation"
+section: "reference"
+slug: "docs-validation"
+tags: ["documentation", "validation", "scripts"]
+weight: 100
+navOrder: 100
+---
+
+# Documentation Validation
+
+> Tools and processes for ensuring documentation completeness
+
+## Overview
+
+CASTQUEST includes automated documentation validation to ensure all features are properly documented with required sections including architecture, setup, environment variables, build & runtime, deployment, and security.
+
+**Code Path:** `infra/scripts/validate-docs.js`
+
+## Purpose
+
+The documentation validation system:
+- **Validates Completeness**: Checks that all features have complete documentation
+- **Enforces Standards**: Ensures consistent documentation structure
+- **Identifies Gaps**: Highlights missing or incomplete sections
+- **Generates Reports**: Creates actionable reports for documentation improvements
+- **CI Integration**: Can be integrated into CI/CD pipelines
+
+## Validation Script
+
+### Location
+
+**Script Path:** `infra/scripts/validate-docs.js`
+
+The validation script is a Node.js script that scans the documentation directory and generates a comprehensive report.
+
+### Usage
+
+#### Running Validation
+
+```bash
+# From repository root
+pnpm validate:docs
+
+# Or directly with node
+node infra/scripts/validate-docs.js
+```
+
+**Output:**
+- Console output with summary
+- `DOCS_VALIDATION_REPORT.md` file in repository root
+
+#### Example Output
+
+```
+✅ Documentation validation complete
+📄 Report generated: /path/to/cast/DOCS_VALIDATION_REPORT.md
+
+Run: cat DOCS_VALIDATION_REPORT.md to view the report
+```
+
+### Validation Criteria
+
+The script checks each feature for the following required sections:
+
+1. **Architecture**: System design, components, integration points
+2. **Setup**: Installation, prerequisites, dependencies
+3. **Environment Variables**: Required and optional configuration
+4. **Build**: Build commands, compilation, bundling
+5. **Deployment**: Deployment procedures, platforms, strategies
+6. **Security**: Security best practices, key management, monitoring
+
+### Status Levels
+
+Documentation sections are categorized:
+
+- **✅ COMPLETE**: Section exists with substantial content (>50 characters, not template)
+- **⚠️ PARTIAL**: Section exists but has template text or minimal content
+- **❌ MISSING**: Section not found in documentation
+
+Overall feature status:
+- **COMPLETE**: All required sections are complete
+- **PARTIAL**: Some sections complete, others partial/missing
+- **INCOMPLETE**: Most sections missing or partial
+- **MISSING**: Documentation directory or files don't exist
+
+## Validated Features
+
+The script validates documentation for:
+
+### 1. SDK (`packages/sdk/`)
+- Docs: `docs-site/sdk/`
+- Key sections: Setup, API reference, examples
+
+### 2. Agents (`packages/agents/`)
+- Docs: `docs-site/agents/`
+- Key sections: Agent types, configuration, monitoring
+
+### 3. Indexer (`packages/indexer/`)
+- Docs: `docs-site/overview/indexer-setup.mdx`
+- Key sections: Database setup, RPC configuration, runtime
+
+### 4. Contracts (`packages/contracts/`)
+- Docs: `docs-site/protocol/`
+- Key sections: Deployment, verification, security
+
+### 5. Web App (`apps/web/`)
+- Docs: `docs-site/overview/web-app-setup.mdx`
+- Key sections: Environment setup, build process, deployment
+
+### 6. Frames
+- Code: `apps/web/` (frames feature)
+- Docs: `docs-site/frames/`
+- Key sections: Farcaster integration, frame types
+
+### 7. Quests
+- Code: `apps/web/` (quests feature)
+- Docs: `docs-site/quests/`
+- Key sections: Quest types, verification, rewards
+
+### 8. Mints
+- Code: `apps/web/` (mints feature)
+- Docs: `docs-site/mints/`
+- Key sections: Mint types, eligibility, pricing
+
+### 9. Marketplace
+- Code: `apps/web/` (marketplace feature)
+- Docs: `docs-site/marketplace/`
+- Key sections: Listings, auctions, royalties
+
+## Validation Report
+
+### Report Structure
+
+The generated `DOCS_VALIDATION_REPORT.md` contains:
+
+1. **Summary**: Overview of documentation completeness
+ - Count of complete, partial, incomplete, missing features
+ - Quick status at a glance
+
+2. **Feature Details**: Detailed breakdown per feature
+ - Feature name and status
+ - Code path reference
+ - Documentation path reference
+ - Environment variables list
+ - Build and test commands
+ - Section-by-section coverage
+
+3. **Recommended Actions**: Prioritized action items
+ - Complete missing sections
+ - Expand partial sections
+ - Add cross-references
+ - Validate commands and variables
+
+4. **Validation Script Info**: How to run validation
+
+### Example Report Section
+
+```markdown
+### ❌ SDK
+
+**Status:** INCOMPLETE
+
+**Code Path:** `packages/sdk/`
+
+**Docs Path:** `docs-site/sdk/`
+
+**Environment Variables:**
+- `CASTQUEST_API_KEY`
+- `CASTQUEST_NETWORK`
+
+**Build Command:** `pnpm --filter @castquest/sdk build`
+
+**Test Command:** `pnpm --filter @castquest/sdk test`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ❌ setup: MISSING
+- ❌ environment variables: MISSING
+- ❌ build: MISSING
+- ❌ deployment: MISSING
+- ❌ security: MISSING
+```
+
+## Adding New Features
+
+To add validation for new features:
+
+1. **Edit Validation Script**: `infra/scripts/validate-docs.js`
+
+2. **Add Feature Entry** to the `FEATURES` array:
+
+```javascript
+{
+ name: 'New Feature',
+ codePath: 'packages/new-feature/',
+ docsPath: 'docs-site/new-feature/',
+ envVars: ['REQUIRED_VAR_1', 'REQUIRED_VAR_2'],
+ buildCommand: 'pnpm --filter @castquest/new-feature build',
+ testCommand: 'pnpm --filter @castquest/new-feature test'
+}
+```
+
+3. **Run Validation** to verify:
+
+```bash
+pnpm validate:docs
+```
+
+## CI Integration
+
+### GitHub Actions
+
+Add to CI workflow (`.github/workflows/ci.yml`):
+
+```yaml
+jobs:
+ validate-docs:
+ name: Validate Documentation
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: 18
+
+ - name: Install pnpm
+ uses: pnpm/action-setup@v2
+ with:
+ version: 8
+
+ - name: Run Documentation Validation
+ run: pnpm validate:docs
+
+ - name: Upload Validation Report
+ if: failure()
+ uses: actions/upload-artifact@v3
+ with:
+ name: docs-validation-report
+ path: DOCS_VALIDATION_REPORT.md
+```
+
+### Pre-commit Hook
+
+Add to `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/bash
+
+# Run docs validation
+echo "Validating documentation..."
+pnpm validate:docs
+
+if [ $? -ne 0 ]; then
+ echo "❌ Documentation validation failed"
+ echo "📄 Review DOCS_VALIDATION_REPORT.md for details"
+ exit 1
+fi
+
+echo "✅ Documentation validation passed"
+```
+
+Make executable:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+## Validation Script Implementation
+
+### Script Structure
+
+The validation script (`infra/scripts/validate-docs.js`):
+
+1. **Feature Configuration**: Array of features to validate
+2. **Section Detection**: Searches for required sections in markdown
+3. **Content Analysis**: Checks if sections have real content (not templates)
+4. **Report Generation**: Creates formatted markdown report
+5. **File Output**: Writes report to `DOCS_VALIDATION_REPORT.md`
+
+### Key Functions
+
+**`hasSectionContent(content, sectionKeywords)`**
+- Searches for section headers
+- Validates content is not template text
+- Returns: COMPLETE, PARTIAL, or MISSING
+
+**`validateFeature(feature)`**
+- Reads all docs for a feature
+- Checks each required section
+- Returns validation results object
+
+**`generateReport()`**
+- Aggregates validation results
+- Formats markdown report
+- Includes recommendations
+
+## Best Practices
+
+### Documentation Standards
+
+When writing documentation:
+
+1. **Include All Required Sections**
+ - Architecture
+ - Setup & Installation
+ - Environment Variables
+ - Build & Development
+ - Deployment
+ - Security
+
+2. **Provide Real Content**
+ - No placeholder text ("Describe the...")
+ - No template variables ($args)
+ - Minimum 50 characters per section
+
+3. **Add Code References**
+ - Specify exact file paths
+ - Link to code examples
+ - Reference specific functions/classes
+
+4. **Validate Commands**
+ - Test all commands before documenting
+ - Include expected output
+ - Note common errors
+
+5. **Document Environment Variables**
+ - List all required variables
+ - Provide example values
+ - Explain where to obtain keys
+
+### Maintaining Documentation
+
+1. **Run Validation Regularly**
+ ```bash
+ pnpm validate:docs
+ ```
+
+2. **Review Reports**
+ - Check DOCS_VALIDATION_REPORT.md
+ - Prioritize MISSING sections
+ - Improve PARTIAL sections
+
+3. **Update After Code Changes**
+ - New features → new docs
+ - API changes → update docs
+ - Deprecations → mark in docs
+
+4. **Peer Review**
+ - Have team members review
+ - Test setup instructions
+ - Verify commands work
+
+## Troubleshooting
+
+### Script Errors
+
+**"Cannot find module"**
+- Run from repository root
+- Ensure Node.js is installed
+
+**"Permission denied"**
+- Make script executable: `chmod +x infra/scripts/validate-docs.js`
+- Or run with node: `node infra/scripts/validate-docs.js`
+
+**"Report not generated"**
+- Check write permissions in repository root
+- Verify disk space available
+
+### False Positives
+
+If a section is marked MISSING but exists:
+
+1. Check section header format (should be `## Section Name` or `### Section Name`)
+2. Ensure section keywords match (see script's `sectionKeywords` mapping)
+3. Verify content is substantial (>50 chars, not template text)
+
+### Customizing Validation
+
+Edit `infra/scripts/validate-docs.js`:
+
+1. Modify `REQUIRED_SECTIONS` array to add/remove sections
+2. Update `sectionKeywords` mapping for section detection
+3. Adjust content validation rules in `hasSectionContent()`
+
+## Related Documentation
+
+- [Contributing Guidelines](https://github.com/CastQuest/cast/blob/main/CONTRIBUTING.md)
+- [Documentation Style Guide](#) (coming soon)
+- [API Documentation Standards](#) (coming soon)
+
+## Support
+
+- **GitHub Issues**: https://github.com/CastQuest/cast/issues
+- **Documentation**: https://docs.castquest.io
+- **Discord**: https://discord.gg/castquest
diff --git a/docs-site/sdk/index.mdx b/docs-site/sdk/index.mdx
index 04e643a..67230f0 100644
--- a/docs-site/sdk/index.mdx
+++ b/docs-site/sdk/index.mdx
@@ -1,60 +1,279 @@
----
-
-title: "Sdk"
+---
+title: "SDK Overview"
section: "sdk"
slug: "index"
-
-tags: ["sdk"]
+tags: ["sdk", "overview"]
weight: 0
navOrder: 0
---
-# Sdk
+# CASTQUEST V3 SDK
-> CASTQUEST V3 — sdk / $args[0].Value.ToUpper() dk
+> TypeScript/JavaScript SDK for CASTQUEST V3 Protocol Integration
## Purpose
-Describe the purpose of this page in the CASTQUEST V3 protocol, including how it connects to:
-- Multi-chain protocol flows
-- Tokenized profiles and marketplace
-- Frames, quests, mints, and workers
-- Governance, buyback, and risk controls
+The CASTQUEST SDK provides a unified interface for developers to interact with the CASTQUEST V3 protocol. It enables:
+
+- **Multi-chain Operations**: Seamless interaction with Base, Ethereum, and L3 networks
+- **Tokenized Profiles**: Profile creation, management, and reputation tracking
+- **Marketplace Integration**: Listing, buying, and selling digital assets
+- **Frames & Quests**: Farcaster frame integration and quest management
+- **AI Agents**: Autonomous agent interactions and revenue participation
+- **Governance**: Voting, proposals, and DAO operations
+
+**Code Path:** `packages/sdk/`
## Architecture
-Explain the core architecture for this topic:
-- Key contracts, agents, or services
-- Data flows and state transitions
-- Integration points (Farcaster, L3, external chains)
+### Core Components
+
+The SDK is organized into modular packages (see `packages/sdk/index.ts`):
+
+```
+@castquest/sdk
+├── wallet (packages/sdk/wallet.ts)
+├── media (packages/sdk/media.ts)
+├── fram (packages/sdk/fram.ts)
+├── game (packages/sdk/game.ts)
+├── code (packages/sdk/code.ts)
+├── marketplace (packages/sdk/marketplace.ts)
+├── agents (packages/sdk/agents.ts)
+├── l3 (packages/sdk/l3.ts)
+├── bridge (packages/sdk/bridge.ts)
+├── governance (packages/sdk/governance.ts)
+└── profile (packages/sdk/profile.ts)
+```
+
+### Technology Stack
+
+- **Language**: TypeScript 5.3+
+- **Build Tool**: tsup (fast TypeScript bundler)
+- **Testing**: Vitest
+- **Web3 Libraries**: ethers v6, viem
+- **Output Formats**: ESM, CommonJS, TypeScript declarations
+
+### Integration Points
+
+1. **Blockchain Networks**
+ - Base mainnet (Chain ID: 8453)
+ - Base Sepolia testnet (Chain ID: 84532)
+ - Ethereum mainnet (Chain ID: 1)
+ - CASTQUEST L3 (custom rollup)
+
+2. **External Services**
+ - Farcaster API for frame integration
+ - IPFS for metadata storage
+ - The Graph for indexing
+
+3. **Protocol Contracts**
+ - Deployed contracts on Base (see `packages/contracts/`)
+ - Multi-chain bridge contracts
+ - Governance contracts
+
+## Key Flows
+
+### 1. SDK Initialization
+
+**Actors**: Developer, End User
+**Inputs**: API key, network configuration
+**Outputs**: Initialized SDK instance
+
+```typescript
+const sdk = new CastQuestSDK({
+ apiKey: process.env.CASTQUEST_API_KEY,
+ network: 'mainnet',
+ chainId: 8453
+});
+```
+
+**Failure Modes**:
+- Invalid API key → Returns authentication error
+- Network unavailable → Retries with exponential backoff
+- Invalid chain ID → Falls back to default (Base mainnet)
+
+### 2. Marketplace Interaction
+
+**Actors**: Buyer, Seller, Marketplace Contract
+**Inputs**: Listing data, payment tokens
+**Outputs**: Transaction hash, ownership transfer
+
+```typescript
+// List item
+const listingId = await sdk.marketplace.createListing({
+ tokenId: '123',
+ price: '1000000000000000000', // 1 ETH in wei
+ duration: 86400 // 24 hours
+});
+
+// Purchase item
+const tx = await sdk.marketplace.purchase(listingId);
+```
+
+**Safeguards**:
+- Price validation (min/max limits)
+- Balance checks before transaction
+- Gas estimation with safety margin
+- Transaction timeout (30 seconds)
+
+### 3. Profile Management
+
+**Actors**: User, Profile Contract
+**Inputs**: Profile data, credentials
+**Outputs**: Profile NFT, reputation score
+
+```typescript
+const profile = await sdk.profile.create({
+ username: 'creator123',
+ bio: 'Digital artist',
+ avatar: 'ipfs://...'
+});
+```
+
+## Build & Runtime
+
+### Build Commands
-## Flows
+```bash
+# Build SDK (from repo root)
+pnpm --filter @castquest/sdk build
-Describe the primary flows:
-- Actors
-- Inputs
-- Outputs
-- Failure modes and safeguards
+# Lint
+pnpm --filter @castquest/sdk lint
+
+# Type check
+pnpm --filter @castquest/sdk typecheck
+
+# Test
+pnpm --filter @castquest/sdk test
+```
+
+### Bundle Configuration
+
+Build configuration in `packages/sdk/tsup.config.ts`:
+- Entry point: `index.ts`
+- Output formats: ESM, CJS
+- Source maps: Enabled in development
+- Tree shaking: Enabled
+- Minification: Production only
+
+### Runtime Requirements
+
+- Node.js >= 18.18.0
+- Modern browser with ES2020 support
+- Web3 provider (MetaMask, WalletConnect, etc.)
+
+## Deployment
+
+### NPM Publishing
+
+```bash
+cd packages/sdk
+npm version patch|minor|major
+npm publish --access public
+```
+
+### Version Strategy
+
+- **Major**: Breaking API changes
+- **Minor**: New features, backward compatible
+- **Patch**: Bug fixes, security patches
+
+### Release Checklist
+
+1. Update version in `package.json`
+2. Update CHANGELOG.md
+3. Run full test suite: `pnpm test:all`
+4. Build production bundle: `pnpm build`
+5. Publish to npm: `npm publish`
+6. Tag release: `git tag v3.0.x`
+7. Create GitHub release with notes
## Metrics & Observability
-List the key metrics, dashboards, and alerts relevant to this topic.
+### API Key Security
-## Implementation Notes
+- **Storage**: Never hardcode keys; use environment variables
+- **Rotation**: Rotate keys every 90 days
+- **Permissions**: Use least-privilege keys for specific operations
+- **Monitoring**: Track API key usage for anomalies
-Add implementation details, edge cases, and migration notes.
+### Transaction Security
-## Next Steps
+- **Signature Verification**: All transactions require wallet signature
+- **Gas Limits**: Automatic gas estimation with 20% safety buffer
+- **Nonce Management**: SDK handles nonce tracking to prevent replay attacks
+- **Timeout Protection**: 30-second timeout on pending transactions
-Link to:
-- Related protocol pages
-- Builder guides
-- SDK references
-- Admin dashboard views
+### Dependency Security
+```bash
+# Run security audit
+pnpm audit --audit-level=high
+# Check for vulnerabilities
+pnpm --filter @castquest/sdk run security:scan
+```
+### Secure Coding Practices
-## Diagram
+- Input validation on all public methods
+- Sanitization of user-provided data
+- No eval() or dynamic code execution
+- Rate limiting on API calls
+
+### Data Privacy
+
+- No logging of private keys or sensitive data
+- Encryption of data at rest and in transit
+- GDPR-compliant data handling
+- User consent for data collection
+
+### Best Practices
+
+- **Never share private keys**: Use hardware wallets for production
+- **Verify contracts**: Always verify contract addresses before interactions
+- **Test on testnets**: Test all integrations on testnets first
+- **Monitor transactions**: Track all SDK transactions in production
+- **Rate limit calls**: Implement client-side rate limiting
+- **Handle errors**: Gracefully handle all error conditions
+- **Keep updated**: Regularly update SDK to latest version
+
+## Metrics & Observability
+
+### Key Metrics
+
+- API request latency (p50, p95, p99)
+- Transaction success rate
+- Error rates by type
+- Active SDK instances
+
+### Error Tracking
+
+SDK errors include structured data:
+```typescript
+{
+ code: 'RATE_LIMIT_EXCEEDED',
+ message: 'Rate limit exceeded',
+ statusCode: 429,
+ retryAfter: 60
+}
+```
+
+### Logging
+
+Enable debug logging:
+```typescript
+const sdk = new CastQuestSDK({
+ debug: true,
+ logLevel: 'verbose'
+});
+```
+
+## Next Steps
-Describe or embed the key architecture or flow diagram for this topic here.
+- [Setup & Installation](/sdk/setup) - Get started with the SDK
+- [Authentication](/sdk/auth) - API key and wallet authentication
+- [TypeScript Examples](/sdk/typescript-examples) - Code examples
+- [Testing Guide](/sdk/testing) - Testing SDK integrations
+- [API Reference](/sdk/api-reference) - Complete method documentation
diff --git a/docs-site/sdk/setup.mdx b/docs-site/sdk/setup.mdx
new file mode 100644
index 0000000..aeed529
--- /dev/null
+++ b/docs-site/sdk/setup.mdx
@@ -0,0 +1,273 @@
+---
+title: "SDK Setup & Installation"
+section: "sdk"
+slug: "setup"
+tags: ["sdk", "setup", "installation"]
+weight: 1
+navOrder: 1
+---
+
+# SDK Setup & Installation
+
+> CASTQUEST V3 — SDK Setup Guide
+
+## Overview
+
+The CASTQUEST SDK (`@castquest/sdk`) is a TypeScript/JavaScript library for interacting with the CASTQUEST V3 protocol. It provides a unified interface for wallet operations, marketplace interactions, frame management, and more.
+
+**Code Path:** `packages/sdk/`
+
+## Prerequisites
+
+Before installing the SDK, ensure you have:
+
+- **Node.js**: >= 18.18.0 (check with `node --version`)
+- **Package Manager**: npm, yarn, or pnpm
+- **TypeScript**: >= 5.3.3 (for TypeScript projects)
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @castquest/sdk
+```
+
+### Using pnpm
+
+```bash
+pnpm add @castquest/sdk
+```
+
+### Using yarn
+
+```bash
+yarn add @castquest/sdk
+```
+
+## Environment Variables
+
+The SDK requires the following environment variables for full functionality:
+
+### Required
+
+- **`CASTQUEST_API_KEY`**: API key for authenticated requests
+ - Obtain from: https://app.castquest.io/settings/api-keys
+ - Example: `cq_live_xxxxxxxxxxxxxxxx`
+
+- **`CASTQUEST_NETWORK`**: Target network for SDK operations
+ - Options: `mainnet`, `testnet`, `local`
+ - Default: `mainnet`
+
+### Optional
+
+- **`CASTQUEST_RPC_URL`**: Custom RPC endpoint
+ - Overrides default network RPC
+ - Example: `https://mainnet.base.org`
+
+- **`CASTQUEST_CHAIN_ID`**: Custom chain ID
+ - Default: 8453 (Base mainnet)
+ - Testnet: 84532 (Base Sepolia)
+
+### Example `.env` file
+
+```bash
+# Required
+CASTQUEST_API_KEY=your_api_key_here_get_from_castquest_dashboard
+CASTQUEST_NETWORK=mainnet
+
+# Optional
+CASTQUEST_RPC_URL=https://mainnet.base.org
+CASTQUEST_CHAIN_ID=8453
+```
+
+## Basic Setup
+
+### TypeScript Setup
+
+```typescript
+import { CastQuestSDK } from '@castquest/sdk';
+
+const sdk = new CastQuestSDK({
+ apiKey: process.env.CASTQUEST_API_KEY,
+ network: process.env.CASTQUEST_NETWORK as 'mainnet' | 'testnet',
+ chainId: parseInt(process.env.CASTQUEST_CHAIN_ID || '8453'),
+});
+
+// Initialize modules
+const { wallet, marketplace, agents } = sdk;
+```
+
+### JavaScript Setup
+
+```javascript
+const { CastQuestSDK } = require('@castquest/sdk');
+
+const sdk = new CastQuestSDK({
+ apiKey: process.env.CASTQUEST_API_KEY,
+ network: process.env.CASTQUEST_NETWORK || 'mainnet',
+});
+
+// Use SDK modules
+sdk.wallet.getBalance(address).then(console.log);
+```
+
+## Available Modules
+
+The SDK exports the following modules (see `packages/sdk/index.ts`):
+
+- **`wallet`**: Wallet operations and balance management
+- **`media`**: Media token operations
+- **`fram`**: Frame token and Farcaster integration
+- **`game`**: Game token and mechanics
+- **`code`**: Code token and builder operations
+- **`marketplace`**: Marketplace listings and transactions
+- **`agents`**: AI agent interactions
+- **`l3`**: Layer 3 operations
+- **`bridge`**: Cross-chain bridging
+- **`governance`**: Governance and voting
+- **`profile`**: User profile management
+
+## Build & Development
+
+### Building the SDK
+
+```bash
+# From repository root
+pnpm --filter @castquest/sdk build
+
+# From packages/sdk directory
+pnpm run build
+```
+
+**Build Output:** `packages/sdk/dist/`
+- `index.js` - CommonJS bundle
+- `index.mjs` - ES Module bundle
+- `index.d.ts` - TypeScript declarations
+
+### Running Tests
+
+```bash
+# From repository root
+pnpm --filter @castquest/sdk test
+
+# From packages/sdk directory
+pnpm run test
+```
+
+### Type Checking
+
+```bash
+pnpm --filter @castquest/sdk typecheck
+```
+
+### Development Mode
+
+Watch mode for automatic rebuilds:
+
+```bash
+pnpm --filter @castquest/sdk dev
+```
+
+## Deployment
+
+### Publishing to npm
+
+The SDK is published to npm as `@castquest/sdk`:
+
+```bash
+# Ensure you're logged in
+npm login
+
+# Publish (from packages/sdk)
+npm publish --access public
+```
+
+**Version Management:**
+- Follow semantic versioning (semver)
+- Update version in `package.json` before publishing
+- Tag releases in git: `git tag v3.0.0`
+
+### CDN Usage
+
+The SDK can be used via CDN for quick prototyping:
+
+```html
+
+```
+
+## Security Best Practices
+
+### API Key Management
+
+- **Never commit API keys** to version control
+- Use environment variables or secure vaults
+- Rotate keys regularly (every 90 days recommended)
+- Use different keys for dev/staging/production
+
+### Rate Limiting
+
+The SDK implements automatic rate limiting:
+- Default: 100 requests per minute
+- Authenticated: 1000 requests per minute
+- Exceeding limits returns 429 status code
+
+### Error Handling
+
+Always wrap SDK calls in try-catch blocks:
+
+```typescript
+try {
+ const balance = await sdk.wallet.getBalance(address);
+ console.log('Balance:', balance);
+} catch (error) {
+ if (error.code === 'RATE_LIMIT_EXCEEDED') {
+ // Handle rate limit
+ } else if (error.code === 'INVALID_API_KEY') {
+ // Handle auth error
+ }
+ console.error('SDK Error:', error.message);
+}
+```
+
+### Secure Communication
+
+- All API calls use HTTPS
+- TLS 1.2+ required
+- Certificate pinning available for mobile apps
+
+## Troubleshooting
+
+### Common Issues
+
+**"Invalid API key" error:**
+- Verify `CASTQUEST_API_KEY` is set correctly
+- Check key hasn't expired
+- Ensure key has required permissions
+
+**"Network not supported" error:**
+- Verify `CASTQUEST_NETWORK` value
+- Check chain ID matches network
+- Confirm RPC endpoint is accessible
+
+**Build failures:**
+- Clear node_modules: `rm -rf node_modules && pnpm install`
+- Ensure TypeScript version >= 5.3.3
+- Check for conflicting dependencies
+
+## Next Steps
+
+- [API Reference](/sdk/api-reference) - Complete SDK method documentation
+- [TypeScript Examples](/sdk/typescript-examples) - Code examples
+- [Authentication](/sdk/auth) - Authentication patterns
+- [Testing Guide](/sdk/testing) - Testing SDK integrations
+
+## Support
+
+- **GitHub Issues**: https://github.com/CastQuest/cast/issues
+- **Documentation**: https://docs.castquest.io/sdk
+- **Discord**: https://discord.gg/castquest
diff --git a/infra/scripts/validate-docs.js b/infra/scripts/validate-docs.js
new file mode 100755
index 0000000..fb9c986
--- /dev/null
+++ b/infra/scripts/validate-docs.js
@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Validation Script
+ *
+ * Validates that all features have complete documentation with required sections:
+ * - architecture
+ * - setup
+ * - environment variables
+ * - build & runtime
+ * - deployment
+ * - security
+ *
+ * Outputs a DOCS_VALIDATION_REPORT.md file with findings.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Required sections for complete documentation
+const REQUIRED_SECTIONS = [
+ 'architecture',
+ 'setup',
+ 'environment variables',
+ 'build',
+ 'deployment',
+ 'security'
+];
+
+// Features to validate (mapped to code paths and doc locations)
+const FEATURES = [
+ {
+ name: 'SDK',
+ codePath: 'packages/sdk/',
+ docsPath: 'docs-site/sdk/',
+ envVars: ['CASTQUEST_API_KEY', 'CASTQUEST_NETWORK'],
+ buildCommand: 'pnpm --filter @castquest/sdk build',
+ testCommand: 'pnpm --filter @castquest/sdk test'
+ },
+ {
+ name: 'Agents',
+ codePath: 'packages/agents/',
+ docsPath: 'docs-site/agents/',
+ envVars: ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'REPLICATE_API_KEY'],
+ buildCommand: 'pnpm --filter @castquest/agents build',
+ testCommand: 'pnpm --filter @castquest/agents test'
+ },
+ {
+ name: 'Indexer',
+ codePath: 'packages/indexer/',
+ docsPath: 'docs-site/overview/',
+ envVars: ['DATABASE_URL', 'REDIS_URL', 'BASE_RPC_URL', 'ETHEREUM_RPC_URL'],
+ buildCommand: 'pnpm --filter @castquest/indexer build',
+ testCommand: 'pnpm --filter @castquest/indexer test'
+ },
+ {
+ name: 'Contracts',
+ codePath: 'packages/contracts/',
+ docsPath: 'docs-site/protocol/',
+ envVars: ['DEPLOYER_PRIVATE_KEY', 'BASE_RPC_URL', 'BASESCAN_API_KEY'],
+ buildCommand: 'pnpm --filter @castquest/contracts build',
+ testCommand: 'pnpm --filter @castquest/contracts test'
+ },
+ {
+ name: 'Web App',
+ codePath: 'apps/web/',
+ docsPath: 'docs-site/overview/',
+ envVars: ['NEXT_PUBLIC_APP_URL', 'DATABASE_URL', 'SESSION_SECRET'],
+ buildCommand: 'pnpm --filter @castquest/web build',
+ testCommand: 'pnpm --filter @castquest/web test'
+ },
+ {
+ name: 'Frames',
+ codePath: 'apps/web/',
+ docsPath: 'docs-site/frames/',
+ envVars: ['FARCASTER_APP_FID', 'FARCASTER_APP_MNEMONIC'],
+ buildCommand: 'pnpm --filter @castquest/web build',
+ testCommand: null
+ },
+ {
+ name: 'Quests',
+ codePath: 'apps/web/',
+ docsPath: 'docs-site/quests/',
+ envVars: [],
+ buildCommand: 'pnpm --filter @castquest/web build',
+ testCommand: null
+ },
+ {
+ name: 'Mints',
+ codePath: 'apps/web/',
+ docsPath: 'docs-site/mints/',
+ envVars: [],
+ buildCommand: 'pnpm --filter @castquest/web build',
+ testCommand: null
+ },
+ {
+ name: 'Marketplace',
+ codePath: 'apps/web/',
+ docsPath: 'docs-site/marketplace/',
+ envVars: [],
+ buildCommand: 'pnpm --filter @castquest/web build',
+ testCommand: null
+ }
+];
+
+// Check if a section exists in documentation content
+function hasSectionContent(content, sectionKeywords) {
+ const lowerContent = content.toLowerCase();
+
+ // Check for section headers
+ for (const keyword of sectionKeywords) {
+ // Match headers with any number of # characters
+ const pattern = new RegExp(`#+\\s*${keyword}`, 'i');
+
+ const match = pattern.exec(content);
+ if (match) {
+ // Check if section has actual content (not just template text)
+ const afterSection = content.substring(match.index + match[0].length);
+ const nextSection = afterSection.indexOf('\n##');
+ const sectionContent = nextSection > -1
+ ? afterSection.substring(0, nextSection)
+ : afterSection;
+
+ // Check if it's not just placeholder text
+ if (!sectionContent.includes('Describe the') &&
+ !sectionContent.includes('Explain the') &&
+ !sectionContent.includes('Add implementation') &&
+ !sectionContent.includes('$args') &&
+ sectionContent.trim().length > 50) {
+ return 'COMPLETE';
+ } else if (sectionContent.trim().length > 10) {
+ return 'PARTIAL';
+ }
+ }
+ }
+ }
+ }
+
+ return 'MISSING';
+}
+
+// Validate a feature's documentation
+function validateFeature(feature) {
+ const rootDir = path.resolve(__dirname, '../..');
+ const docsDir = path.join(rootDir, feature.docsPath);
+
+ const results = {
+ feature: feature.name,
+ codePath: feature.codePath,
+ docsPath: feature.docsPath,
+ sections: {},
+ overall: 'COMPLETE'
+ };
+
+ // Check if docs directory exists
+ if (!fs.existsSync(docsDir)) {
+ results.overall = 'MISSING';
+ return results;
+ }
+
+ // Read all markdown files in docs directory
+ let allDocsContent = '';
+ try {
+ const files = fs.readdirSync(docsDir);
+ const mdFiles = files.filter(f => f.endsWith('.md') || f.endsWith('.mdx'));
+
+ for (const file of mdFiles) {
+ const filePath = path.join(docsDir, file);
+ const content = fs.readFileSync(filePath, 'utf-8');
+ allDocsContent += content + '\n';
+ }
+ } catch (err) {
+ results.overall = 'MISSING';
+ return results;
+ }
+
+ // Check each required section
+ const sectionKeywords = {
+ 'architecture': ['architecture', 'design', 'structure', 'components'],
+ 'setup': ['setup', 'installation', 'getting started', 'prerequisites', 'dependencies'],
+ 'environment variables': ['environment variables', 'env vars', 'configuration', 'env', 'environment'],
+ 'build': ['build', 'compile', 'bundling', 'building'],
+ 'deployment': ['deployment', 'deploy', 'publishing', 'release'],
+ 'security': ['security', 'authentication', 'authorization', 'vulnerabilities', 'secrets']
+ };
+
+ for (const section of REQUIRED_SECTIONS) {
+ const keywords = sectionKeywords[section] || [section];
+ const status = hasSectionContent(allDocsContent, keywords);
+ results.sections[section] = status;
+
+ if (status === 'MISSING') {
+ results.overall = 'INCOMPLETE';
+ } else if (status === 'PARTIAL' && results.overall === 'COMPLETE') {
+ results.overall = 'PARTIAL';
+ }
+ }
+
+ return results;
+}
+
+// Generate the validation report
+function generateReport() {
+ const results = FEATURES.map(validateFeature);
+
+ let report = `# Documentation Validation Report\n\n`;
+ report += `Generated: ${new Date().toISOString()}\n\n`;
+ report += `This report identifies documentation gaps across the CastQuest repository.\n`;
+ report += `Each feature should have complete documentation covering:\n`;
+ report += REQUIRED_SECTIONS.map(s => `- ${s}`).join('\n') + '\n\n';
+
+ report += `## Summary\n\n`;
+ const complete = results.filter(r => r.overall === 'COMPLETE').length;
+ const partial = results.filter(r => r.overall === 'PARTIAL').length;
+ const incomplete = results.filter(r => r.overall === 'INCOMPLETE').length;
+ const missing = results.filter(r => r.overall === 'MISSING').length;
+
+ report += `- ✅ Complete: ${complete}\n`;
+ report += `- ⚠️ Partial: ${partial}\n`;
+ report += `- ❌ Incomplete: ${incomplete}\n`;
+ report += `- 🚫 Missing: ${missing}\n\n`;
+
+ report += `## Feature Details\n\n`;
+
+ for (const result of results) {
+ const icon = result.overall === 'COMPLETE' ? '✅' :
+ result.overall === 'PARTIAL' ? '⚠️' :
+ result.overall === 'INCOMPLETE' ? '❌' : '🚫';
+
+ report += `### ${icon} ${result.feature}\n\n`;
+ report += `**Status:** ${result.overall}\n\n`;
+ report += `**Code Path:** \`${result.codePath}\`\n\n`;
+ report += `**Docs Path:** \`${result.docsPath}\`\n\n`;
+
+ const feature = FEATURES.find(f => f.name === result.feature);
+
+ if (feature.envVars && feature.envVars.length > 0) {
+ report += `**Environment Variables:**\n`;
+ for (const envVar of feature.envVars) {
+ report += `- \`${envVar}\`\n`;
+ }
+ report += `\n`;
+ }
+
+ if (feature.buildCommand) {
+ report += `**Build Command:** \`${feature.buildCommand}\`\n\n`;
+ }
+
+ if (feature.testCommand) {
+ report += `**Test Command:** \`${feature.testCommand}\`\n\n`;
+ }
+
+ report += `**Section Coverage:**\n\n`;
+ for (const [section, status] of Object.entries(result.sections)) {
+ const sectionIcon = status === 'COMPLETE' ? '✅' :
+ status === 'PARTIAL' ? '⚠️' : '❌';
+ report += `- ${sectionIcon} ${section}: ${status}\n`;
+ }
+ report += `\n`;
+ }
+
+ report += `## Recommended Actions\n\n`;
+ report += `1. Complete all MISSING sections with actual content\n`;
+ report += `2. Expand PARTIAL sections with complete information\n`;
+ report += `3. Add cross-references to code paths in each doc\n`;
+ report += `4. Validate all commands and environment variable names\n`;
+ report += `5. Include security best practices in each feature doc\n\n`;
+
+ report += `## Validation Script\n\n`;
+ report += `To run this validation:\n`;
+ report += `\`\`\`bash\n`;
+ report += `pnpm validate:docs\n`;
+ report += `\`\`\`\n\n`;
+ report += `The script checks:\n`;
+ report += `- Existence of documentation files\n`;
+ report += `- Presence of required sections\n`;
+ report += `- Content completeness (not just templates)\n`;
+ report += `- Cross-references to code paths\n`;
+
+ return report;
+}
+
+// Main execution
+const report = generateReport();
+const reportPath = path.resolve(__dirname, '../../DOCS_VALIDATION_REPORT.md');
+fs.writeFileSync(reportPath, report);
+
+console.log('✅ Documentation validation complete');
+console.log(`📄 Report generated: ${reportPath}`);
+console.log('\nRun: cat DOCS_VALIDATION_REPORT.md to view the report');
diff --git a/package.json b/package.json
index c5962aa..80b2296 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,7 @@
"validate:docker": "docker compose -f infra/docker-compose.yml config > /dev/null",
"validate:k8s": "node infra/scripts/validate-k8s.js",
"validate:terraform": "cd infra/terraform && terraform fmt -check && terraform validate",
- "validate:docs": "node scripts/validate-docs.js",
+ "validate:docs": "node infra/scripts/validate-docs.js",
"clean": "turbo clean && rm -rf node_modules .turbo",
"orchestrate:v3": "pwsh ./infra/Orchestration.ps1"
},