Complete Coins Documentation Overhaul with Native Mermaid Support (#1327)

## Summary

This PR delivers a comprehensive overhaul of the Zora Coins documentation with improved user experience, native Mermaid diagram support, and better navigation structure. The changes transform the documentation from technical reference material into practical developer guides while fixing broken links and improving overall organization.

## 🎯 Key Improvements

### 📚 Documentation Transformation
- **Native Mermaid Support**: Implemented `remark-mermaidjs` plugin for native ````mermaid syntax instead of React components
- **User-Centric Design**: Restructured all documentation to focus on "how to use" rather than technical implementation details  
- **Improved Navigation**: Fixed broken links, updated navigation structure, and reorganized content hierarchy
- **Practical Examples**: Added extensive Solidity code examples with proper ABI encoding structures
- **Authentic Messaging**: Updated language to align with authentic Zora terminology

### 🏗️ Content Structure Overhaul
- **Renamed Pages**: `factory.mdx` → `creating-a-coin.mdx` for better discoverability
- **New Architecture Page**: Comprehensive technical deep-dive separated from user guides
- **Protocol Branding**: Updated "Zora Protocol" → "Zora Coins Protocol" throughout
- **Reward System**: Renamed "Protocol Rewards" → "Coin Rewards" for clarity

## 📋 Major Documentation Changes

### New Content Structure
- **Coins Homepage** (`/coins/index.mdx`): Complete redesign focusing on protocol overview and developer resources
- **Creating a Coin** (`/coins/contracts/creating-a-coin.mdx`): Developer-focused guide with proper ABI encoding examples
- **Architecture** (`/coins/contracts/architecture.mdx`): Technical deep-dive with UML diagrams
- **Contracts Overview** (`/coins/contracts/index.mdx`): Simplified navigation hub with contract summaries

### Native Mermaid Integration
- **Removed Dependencies**: Eliminated `rehype-mermaid`, `mermaid`, `react-zoom-pan-pinch`
- **Added Plugin**: Configured `remark-mermaidjs` for native markdown processing
- **Converted Diagrams**: All React Mermaid components → native ````mermaid code blocks

### Technical Improvements
- **Fixed Pool Configuration**: Removed incorrect fee configuration, added proper ABI encoding structure
- **Doppler Integration**: Added references to [Doppler protocol](https://whetstone.cc/doppler) for initial liquidity positioning
- **Creator Clarification**: Added important notes about `msg.sender` being considered the creator
- **Indexer Behavior**: Documented that only the first creator coin is recognized by the Zora indexer

### Content Quality Improvements
- **Removed Second-Person Language**: Eliminated "you/your" throughout documentation per style guidelines
- **Fixed Dead Links**: Updated all broken references from removed pages and renamed files
- **Strategic Cross-Linking**: Added internal links to improve user journey and discoverability
- **Homepage Card**: Updated main navigation card with better description

## 🔧 Technical Implementation Details

### Mermaid Configuration
```typescript
// docs/vocs.config.ts
import remarkMermaid from "remark-mermaidjs";

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMermaid],
  },
});
```

### ABI Encoding Examples
Updated all pool configuration examples to show proper encoding:
```solidity
abi.encode(
    uint8(4),                                    // version
    ZORA_TOKEN_ADDRESS,                         // currency
    [-90000, -74000, -62000],                   // tickLower array
    [-58500, -67000, -52000],                   // tickUpper array  
    [11, 11, 11],                               // numDiscoveryPositions
    [0.05e18, 0.1e18, 0.1e18]                   // maxDiscoverySupplyShare (WAD)
)
```

### Navigation Structure
- **Fixed Links**: All `/coins/contracts/factory` → `/coins/contracts/creating-a-coin`
- **Updated Config**: Navigation properly reflects actual file structure
- **Removed Dead References**: Eliminated references to non-existent getting-started page

## 📝 Files Changed

### Documentation (18 files)
- Complete overhaul of coins documentation structure
- Native Mermaid diagram implementation
- Updated navigation and cross-references
- Fixed broken links and improved organization

### Configuration (3 files) 
- Vocs configuration for Mermaid support
- Package.json dependency updates
- Navigation structure improvements

## 🚀 User Experience Impact

### For Developers
- **Clear Examples**: Proper Solidity code with correct ABI encoding
- **Better Flow**: Logical progression from overview → creation → technical details
- **Native Diagrams**: Mermaid diagrams render directly in documentation without React overhead

### For Content Creators
- **Simplified Language**: Removed technical jargon and second-person references
- **Better Organization**: Clear separation between user guides and technical reference
- **Authentic Voice**: Documentation now uses official Zora terminology and messaging

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: oveddan

CLAUDE.md

@@ -2,6 +2,26 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Documentation Philosophy
+
+### Contract Documentation Guidelines
+
+When documenting contracts, focus on **how to use** and **how it works** rather than technical reference material:
+
+- **Prioritize user goals**: What does someone want to accomplish? (e.g., "Create a coin", "Understand rewards")
+- **Use practical examples**: Show real code snippets and configuration values
+- **Explain the "why"**: Help users understand the purpose and trade-offs of different options
+- **Visual diagrams**: Use UML diagrams to show relationships and processes
+- **Avoid redundancy**: Don't repeat information covered in other sections
+- **Remove deprecated methods**: Only document current recommended approaches
+
+### Writing Style for Contracts
+
+- Use action-oriented headings (e.g., "Creating a Coin" vs "Coin Creation")
+- Lead with benefits and outcomes, not implementation details
+- Include decision-making guidance (e.g., "Use this configuration if...", "Choose based on...")
+- Link strategically to related concepts and next steps
+
 ## Development Commands
 
 ### GitHub Actions Integration

docs/CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md - Docs
+
+This file provides guidance to Claude Code when working with the documentation in this directory.
+
+## UML Diagrams
+
+### Generating UML Diagrams
+
+When you create or update PlantUML diagrams in the `uml/` directory:
+
+1. **Create/update the .puml file** in `uml/` directory
+2. **Generate the SVG** by running:
+   ```bash
+   cd docs
+   pnpm generate-uml
+   ```
+3. **Reference the generated SVG** in documentation using the path: `public/uml/filename.svg`
+
+### UML File Locations
+
+- **Source files**: `uml/*.puml` (PlantUML format)
+- **Generated files**: `public/uml/*.svg` (SVG format for web display)
+
+### Example
+
+For a file `uml/my-diagram.puml`, the generated SVG will be at `public/uml/my-diagram.svg` and can be referenced in documentation as:
+
+```markdown
+![My Diagram](/uml/my-diagram.svg)
+```
+
+Note: Use the `/uml/` path (not `public/uml/`) when referencing diagrams in documentation.
+
+## Prerequisites for Docs Development
+
+Before working with the documentation, you need to build the packages that are imported:
+
+1. **Install dependencies** from the root directory:
+   ```bash
+   cd /Users/danovedzora/source/protocol-clones/zora-protocol-agent-1
+   pnpm install
+   ```
+
+2. **Build packages** from the root directory:
+   ```bash
+   pnpm build
+   ```
+   Note: If the build fails due to missing dependencies (like `tsc`), you may need to install TypeScript globally or ensure all dependencies are properly installed.
+
+3. **Start docs development server**:
+   ```bash
+   cd docs
+   pnpm dev
+   ```
+
+## Writing Guidelines
+
+- **Avoid second person language**: Never use "you", "your", "yours" in documentation. Use third person (e.g., "the user", "developers", "coin creators") or imperative voice (e.g., "Call the function", "Set the parameter") instead.
+
+## Redirects Management
+
+### When Renaming or Moving Documentation Files
+
+When renaming or moving documentation files, always add redirects to `docs/vercel.json` to prevent broken links:
+
+1. **Add redirect entries** in the `redirects` array
+2. **Use permanent redirects** (`"permanent": true`) for renamed pages
+3. **Use temporary redirects** (`"permanent": false`) for content that may change
+
+### Example Redirect Entry
+
+```json
+{
+  "source": "/coins/contracts/factory",
+  "destination": "/coins/contracts/creating-a-coin", 
+  "permanent": true
+}
+```
+
+### Common Redirect Scenarios
+
+- **Page renamed**: Redirect old URL to new URL
+- **Page moved**: Redirect old path to new path  
+- **Page removed**: Redirect to most relevant existing page
+- **Section reorganized**: Redirect old structure to new structure
+
+Always test redirects after deployment to ensure they work correctly.
+
+## Development Commands
+
+- `pnpm generate-uml` - Generate SVG files from PlantUML source files
+- `pnpm dev` - Start development server
+- `pnpm build` - Build documentation site

docs/package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "dev": "vocs dev",
     "build": "tsc --noEmit",
-    "build:site": "vocs build",
+    "build:site": "playwright install --with-deps chromium && vocs build",
     "preview": "vocs preview",
     "copy-changelog": "tsx scripts/copy-changelogs.ts",
     "generate-uml": "tsx scripts/generateUml.ts"
@@ -21,8 +21,11 @@
     "@zoralabs/coins-sdk": "workspace:*",
     "@zoralabs/protocol-deployments": "workspace:*",
     "@zoralabs/protocol-sdk": "workspace:*",
+    "clsx": "^2.1.1",
+    "playwright": "^1.54.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "remark-mermaidjs": "^7.0.0",
     "typescript": "^5.2.2",
     "viem": "^2.21.21",
     "vite": "^5.4.8",

docs/pages/coins/contracts/architecture.mdx

@@ -0,0 +1,150 @@
+# Contract Architecture
+
+This page provides a technical overview of how the Coins protocol contracts work together to enable coin creation, trading, and automatic reward distribution.
+
+## Architecture Overview
+
+```mermaid
+classDiagram
+    %% Uniswap V4 Package
+    class IPoolManager {
+        +initialize()
+        +modifyLiquidity()
+        +swap()
+        +take()
+    }
+    
+    %% Factory Package
+    class ZoraFactoryImpl {
+        +deploy(payoutRecipient, owners, uri, name, symbol, poolConfig, platformReferrer, postDeployHook, postDeployHookData, coinSalt)
+        +deployCreatorCoin(payoutRecipient, owners, uri, name, symbol, poolConfig, platformReferrer, coinSalt)
+        +coinAddress(msgSender, name, symbol, poolConfig, platformReferrer, coinSalt)
+        +coinImpl()
+    }
+    
+    %% Coins Package
+    class BaseCoinV4 {
+        <<abstract>>
+        #poolManager: IPoolManager
+        #poolKey: PoolKey
+        +migrateLiquidity()
+        +getPayoutSwapPath()
+    }
+    
+    class CreatorCoin {
+        -currency: ZORA
+        -vestingSchedule: VestingSchedule
+        +claimVesting()
+        +getClaimableAmount()
+    }
+    
+    class ContentCoin {
+        -backingCurrency: CreatorCoin
+        +rewardsDistributionMethodology()
+    }
+    
+    %% Hooks Package
+    class BaseZoraV4CoinHook {
+        <<abstract>>
+        +afterInitialize()
+        +afterSwap()
+        -collectFees()
+        -mintLpReward()
+        +_distributeMarketRewards()
+    }
+    
+    class ContentCoinHook {
+        +_distributeMarketRewards()
+    }
+    
+    class CreatorCoinHook {
+        +_distributeMarketRewards()
+    }
+    
+    class ZORAToken {
+        ZORA Token
+    }
+    
+    %% Inheritance relationships
+    BaseCoinV4 <|-- CreatorCoin
+    BaseCoinV4 <|-- ContentCoin
+    BaseZoraV4CoinHook <|-- ContentCoinHook
+    BaseZoraV4CoinHook <|-- CreatorCoinHook
+    
+    %% Factory relationships
+    ZoraFactoryImpl ..> CreatorCoin : creates
+    ZoraFactoryImpl ..> ContentCoin : creates
+    
+    %% Hook relationships
+    BaseZoraV4CoinHook --> IPoolManager : uses
+    ContentCoinHook --> BaseCoinV4 : manages rewards
+    CreatorCoinHook --> BaseCoinV4 : manages rewards
+    
+    %% Pool Manager relationships
+    BaseCoinV4 --> IPoolManager : integrates with
+    CreatorCoin --> CreatorCoinHook : uses hook
+    ContentCoin --> ContentCoinHook : uses hook
+    
+    %% Currency relationships
+    ContentCoin --> CreatorCoin : backed by
+    CreatorCoin --> ZORAToken : backed by
+```
+
+*Visual overview of how contracts work together in the Zora Coins system*
+
+## Core Components
+
+### Coins Contracts
+
+**BaseCoinV4 (Abstract)**
+- Base implementation for both coin types
+- Integrates with Uniswap V4 PoolManager
+- Handles liquidity migration between hook versions
+- Manages pool key and basic coin functionality
+
+**CreatorCoin**
+- One per creator, backed by ZORA tokens
+- 1 billion total supply with 5-year vesting schedule
+- 500M tokens vest to creator, 500M available for trading
+- Simpler reward distribution (creator + protocol)
+
+**ContentCoin**
+- Multiple per creator, backed by creator's coin
+- 1 billion total supply with instant creator allocation
+- 10M tokens to creator immediately, 990M available for trading
+- Complex reward distribution including referrals
+
+### Factory Contract
+
+**ZoraFactoryImpl**
+- Deploys new coins with deterministic addresses
+- Supports custom pool configurations and post-deployment hooks
+- Creates Uniswap V4 pools automatically with appropriate hook contracts
+- Provides address prediction before deployment
+
+Key functions:
+- `deploy()` - General coin deployment with full customization
+- `deployCreatorCoin()` - Simplified Creator Coin deployment
+- `coinAddress()` - Predict deployment address before deploying
+
+### Hook System
+
+The protocol uses an inheritance-based hook architecture:
+
+**BaseZoraV4CoinHook (Abstract)**
+- Contains all shared hook functionality for both coin types
+- Implements Uniswap V4 hook interface (`afterSwap`, `afterInitialize`)
+- Handles pool initialization, fee collection, and currency conversion
+- Supports migration to new hook versions while preserving liquidity
+
+**ContentCoinHook & CreatorCoinHook**
+- Inherit from `BaseZoraV4CoinHook` but override reward distribution
+- ContentCoinHook: Distributes rewards to create referral, trade referral, creator, protocol, and Doppler
+- CreatorCoinHook: Distributes rewards to creator and protocol only
+
+Core shared functionality:
+- Collects trading fees from liquidity positions
+- Splits fees between LP rewards (33.33%) and market rewards (66.67%)
+- Converts fees to backing currency via multi-hop swaps
+- Distributes rewards based on coin-specific methodology
+