Complete feature documentation with validation tooling

DOCS_VALIDATION_REPORT.md

@@ -0,0 +1,252 @@
+# Documentation Validation Report
+
+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
+
+## Summary
+
+- ✅ Complete: 0
+- ⚠️ Partial: 3
+- ❌ Incomplete: 6
+- 🚫 Missing: 0
+
+## Feature Details
+
+### ⚠️ SDK
+
+**Status:** PARTIAL
+
+**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: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ⚠️ security: PARTIAL
+
+### ❌ Agents
+
+**Status:** INCOMPLETE
+
+**Code Path:** `packages/agents/`
+
+**Docs Path:** `docs-site/agents/`
+
+**Environment Variables:**
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `REPLICATE_API_KEY`
+
+**Build Command:** `pnpm --filter @castquest/agents build`
+
+**Test Command:** `pnpm --filter @castquest/agents test`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
+
+### ❌ Indexer
+
+**Status:** INCOMPLETE
+
+**Code Path:** `packages/indexer/`
+
+**Docs Path:** `docs-site/overview/`
+
+**Environment Variables:**
+- `DATABASE_URL`
+- `REDIS_URL`
+- `BASE_RPC_URL`
+- `ETHEREUM_RPC_URL`
+
+**Build Command:** `pnpm --filter @castquest/indexer build`
+
+**Test Command:** `pnpm --filter @castquest/indexer test`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ⚠️ build: PARTIAL
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
+
+### ❌ Contracts
+
+**Status:** INCOMPLETE
+
+**Code Path:** `packages/contracts/`
+
+**Docs Path:** `docs-site/protocol/`
+
+**Environment Variables:**
+- `DEPLOYER_PRIVATE_KEY`
+- `BASE_RPC_URL`
+- `BASESCAN_API_KEY`
+
+**Build Command:** `pnpm --filter @castquest/contracts build`
+
+**Test Command:** `pnpm --filter @castquest/contracts test`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
+
+### ❌ Web App
+
+**Status:** INCOMPLETE
+
+**Code Path:** `apps/web/`
+
+**Docs Path:** `docs-site/overview/`
+
+**Environment Variables:**
+- `NEXT_PUBLIC_APP_URL`
+- `DATABASE_URL`
+- `SESSION_SECRET`
+
+**Build Command:** `pnpm --filter @castquest/web build`
+
+**Test Command:** `pnpm --filter @castquest/web test`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ⚠️ build: PARTIAL
+- ❌ deployment: MISSING
+- ✅ security: COMPLETE
+
+### ⚠️ Frames
+
+**Status:** PARTIAL
+
+**Code Path:** `apps/web/`
+
+**Docs Path:** `docs-site/frames/`
+
+**Environment Variables:**
+- `FARCASTER_APP_FID`
+- `FARCASTER_APP_MNEMONIC`
+
+**Build Command:** `pnpm --filter @castquest/web build`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ✅ security: COMPLETE
+
+### ❌ Quests
+
+**Status:** INCOMPLETE
+
+**Code Path:** `apps/web/`
+
+**Docs Path:** `docs-site/quests/`
+
+**Build Command:** `pnpm --filter @castquest/web build`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
+
+### ⚠️ Mints
+
+**Status:** PARTIAL
+
+**Code Path:** `apps/web/`
+
+**Docs Path:** `docs-site/mints/`
+
+**Build Command:** `pnpm --filter @castquest/web build`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ⚠️ environment variables: PARTIAL
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ✅ security: COMPLETE
+
+### ❌ Marketplace
+
+**Status:** INCOMPLETE
+
+**Code Path:** `apps/web/`
+
+**Docs Path:** `docs-site/marketplace/`
+
+**Build Command:** `pnpm --filter @castquest/web build`
+
+**Section Coverage:**
+
+- ⚠️ architecture: PARTIAL
+- ✅ setup: COMPLETE
+- ✅ environment variables: COMPLETE
+- ✅ build: COMPLETE
+- ✅ deployment: COMPLETE
+- ❌ security: MISSING
+
+## 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
+
+To run this validation:
+```bash
+pnpm validate:docs
+```
+
+The script checks:
+- Existence of documentation files
+- Presence of required sections
+- Content completeness (not just templates)
+- Cross-references to code paths