Claude Code Configuration - Documentation Directory

Directory Purpose: GitHub Pages documentation site (riddlen.org)

🎯 What This Directory Is For

This directory contains public-facing documentation that gets published to riddlen.org via GitHub Pages.

Content Types

What Lives Here

What Does NOT Live Here

📁 Stay In Your Lane

Work ONLY on documentation files in this directory

When you need to reference other directories:

🔒 Security Policy

⚠️ Files to NEVER Access

Public Information Only

See ../.claudeignore for complete list.

🔄 Git Workflow

Before Making Changes

# 1. Make sure you're in docs/
cd /var/www/riddlen/docs

# 2. Check git status
git status

# 3. Create feature branch if needed
git checkout -b docs/update-integration-guide

Making Changes

  1. Edit documentation files (*.md)
  2. Test links - ensure all links work
  3. Check formatting - preview markdown rendering
  4. Verify accuracy - ensure technical details are correct

Testing Your Changes

# Preview locally (if Jekyll/GitHub Pages setup)
bundle exec jekyll serve

# Or use markdown preview in editor
# Verify all links work
# Check code snippets are correct

Committing Changes

# Add only docs files
git add docs/

# Commit with clear message
git commit -m "docs: update frontend integration guide with Wagmi v2 examples"

# Push to branch
git push origin docs/update-integration-guide

Commit Message Format

docs: <what you changed>

Examples:
- docs: add RON reputation tier guide
- docs: update contract addresses for mainnet
- docs: fix broken links in integration guide
- docs: improve tokenomics documentation

✅ Testing & Verification

Before Committing

Validation Checklist

  1. Links: Click every link to verify
  2. Code: Test any code snippets
  3. Addresses: Verify contract addresses on block explorer
  4. Formatting: Check headers, lists, code blocks
  5. Images: Ensure any images load correctly

📋 Audit & Review

Self-Audit Before Commit

Peer Review (Optional)

For major documentation updates:

# Create pull request for review
gh pr create --title "docs: major update to integration guide" \
  --body "Updated integration guide with latest contract changes"

🧹 Keep It Clean

File Organization

docs/
├── README.md              # Index/overview
├── integration/           # Integration guides
├── contracts/             # Contract documentation
├── guides/                # User guides
├── api/                   # API reference
└── architecture/          # System architecture

Naming Conventions

Regular Cleanup

# Remove outdated docs
mv old-guide.md archive/

# Update stale information
grep -r "TODO" docs/  # Find incomplete docs
grep -r "OUTDATED" docs/  # Find docs marked for update

📦 Archive Strategy

When to Archive

How to Archive

# Create archive directory if needed
mkdir -p docs/archive/v1

# Move old docs
mv docs/old-integration-guide.md docs/archive/v1/

# Add note in main doc
echo "See archive/v1/ for legacy documentation" >> README.md

# Commit archive
git add docs/archive/
git commit -m "docs: archive v1 integration guides"

Archive Structure

docs/archive/
├── v1/           # Version 1 docs
├── v2/           # Version 2 docs
└── deprecated/   # Deprecated features

📝 Documentation Standards

Markdown Formatting

Code Examples

// ✅ Good: Include context and comments
import { useAccount } from 'wagmi';

// Connect wallet and get address
const { address } = useAccount();

// ❌ Bad: No context
const { address } = useAccount();

Contract Addresses

Always specify network:

## Contract Addresses

### Polygon Amoy Testnet (Chain ID: 80002)
- RDLN: `0x133029184EC460F661d05b0dC57BFC916b4AB0eB`
- RON: `0xD86b146Ed091b59cE050B9d40f8e2760f14Ab635`

🔗 Related Directories

When Documenting…

Cross-References

For contract source code, see [contracts/](../contracts/)
For testnet addresses, see [testnet deployment](../testnet/TESTNET_DEPLOYMENT.md)

🚀 Publishing to riddlen.org

GitHub Pages Setup

This directory publishes to riddlen.org via GitHub Pages.

Publication Workflow

  1. Commit changes to main branch (or docs branch)
  2. GitHub Actions automatically builds site
  3. Changes appear on riddlen.org within minutes

Preview Before Publishing

# Test locally before pushing
bundle exec jekyll serve --watch

# Visit http://localhost:4000
# Verify changes look correct

⚠️ Common Mistakes to Avoid

❌ Don’t Do This

✅ Do This Instead

📊 Documentation Metrics

Keep Track Of

Add Frontmatter

---
title: Frontend Integration Guide
last_updated: 2025-10-02
version: 5.2
status: current
---

🎯 Summary: Your Role

When working in docs/:

✅ DO:

❌ DON’T:

Goal: Maintain high-quality public documentation for riddlen.org that helps developers and users understand and integrate with Riddlen.

Related Files: