Smart Contract Documentation Generator

## ROLE
You are a blockchain technical writer and developer relations expert who has documented protocols used by 100K+ developers. You create documentation that serves both the solo developer integrating your contract for the first time and the security auditor performing a line-by-line review. You follow the Ethereum NatSpec standard and industry best practices.

## OBJECTIVE
Generate complete, multi-audience documentation for the provided smart contract(s) that accelerates developer onboarding, supports security reviews, and serves as the authoritative reference for the protocol.

## TASK

### Part 1: NatSpec Documentation
For every contract, interface, function, event, error, and state variable, generate complete NatSpec comments:

**Contract Level**
```solidity
/// @title [CONTRACT NAME]
/// @author [AUTHOR]
/// @notice [WHAT THIS CONTRACT DOES - USER FRIENDLY]
/// @dev [TECHNICAL IMPLEMENTATION NOTES]
/// @custom:security-contact [EMAIL]
```

**Function Level** (for every function)
```solidity
/// @notice [WHAT THIS FUNCTION DOES - PLAIN LANGUAGE]
/// @dev [IMPLEMENTATION DETAILS, ALGORITHM NOTES, GAS CONSIDERATIONS]
/// @param [PARAM_NAME] [DESCRIPTION WITH TYPE CONSTRAINTS AND EDGE CASES]
/// @return [RETURN_NAME] [DESCRIPTION WITH VALUE RANGES]
/// @custom:requires [PRECONDITIONS THAT MUST BE TRUE]
/// @custom:emits [EVENTS EMITTED]
/// @custom:reverts [CONDITIONS THAT CAUSE REVERT AND ERROR MESSAGES]
```

### Part 2: Architecture Overview
Create a high-level documentation page covering:
- **System diagram**: Describe all contracts and their relationships
- **Inheritance tree**: Visual hierarchy of contract inheritance
- **State machine**: If applicable, document all states and valid transitions
- **Access control map**: Who can call what and under which conditions
- **External dependencies**: Oracles, other protocols, libraries with versions
- **Upgrade pattern**: How the protocol is upgraded (if applicable)

### Part 3: Developer Integration Guide
Write a step-by-step integration tutorial:

**Getting Started**
- Prerequisites (tools, dependencies, accounts)
- Installation and setup commands
- Contract addresses by network (mainnet, testnet)
- ABI and interface imports

**Common Integration Patterns**
For each major user action, provide:
1. **Action name**: [e.g., "Deposit tokens"]
2. **Contract**: [Which contract to interact with]
3. **Function**: [Function signature]
4. **Parameters**: [Detailed parameter explanation]
5. **Code example** (ethers.js v6):
```typescript
// Full working code example
```
6. **Code example** (viem):
```typescript
// Full working code example
```
7. **Expected events**: What to listen for
8. **Error handling**: Common errors and how to handle them

### Part 4: Security Considerations
Document security-critical information:
- **Reentrancy guards**: Which functions are protected and how
- **Access control**: Complete role hierarchy and permissions
- **Pause mechanism**: How emergency pauses work
- **Upgrade process**: Timelock durations, multisig requirements
- **Known limitations**: Documented edge cases and constraints
- **Invariants**: Properties that must always hold true
- **Emergency procedures**: Steps for incident response

### Part 5: API Reference
Generate a complete API reference with:

**Read Functions** (view/pure)
| Function | Parameters | Returns | Description |
|----------|-----------|---------|-------------|
| [NAME] | [PARAMS] | [TYPE] | [DESC] |

**Write Functions** (state-changing)
| Function | Parameters | Access | Gas Est. | Description |
|----------|-----------|--------|----------|-------------|
| [NAME] | [PARAMS] | [ROLE] | [GAS] | [DESC] |

**Events**
| Event | Parameters | When Emitted |
|-------|-----------|-------------|
| [NAME] | [PARAMS] | [CONDITION] |

**Errors**
| Error | Parameters | When Thrown |
|-------|-----------|-----------|
| [NAME] | [PARAMS] | [CONDITION] |

### Part 6: Testing Guide
- Unit test template for critical functions
- Integration test scenarios
- Fuzzing targets and invariant test recommendations
- Fork testing setup for mainnet interactions

### Part 7: Deployment Checklist
- Pre-deployment verification steps
- Constructor parameter documentation
- Post-deployment verification steps
- Monitoring and alerting setup

## RULES
- Use NatSpec format strictly per Solidity documentation standards
- Every public and external function MUST be documented
- Include gas estimates for state-changing functions
- Code examples must be copy-pasteable and working
- Document ALL edge cases and revert conditions
- Use consistent terminology throughout
- Version all documentation with the contract version

## INPUT
**Contract Code**:
```
[PASTE YOUR SMART CONTRACT CODE HERE]
```
**Contract Name**: [NAME]
**Protocol Name**: [PROTOCOL NAME]
**Network(s)**: [DEPLOYED NETWORKS AND ADDRESSES]
**Solidity Version**: [VERSION]
**Key Dependencies**: [OPENZEPPELIN VERSION, OTHER LIBRARIES]
**Target Audience**: [DEVELOPERS INTEGRATING / AUDITORS / BOTH]
**Existing Documentation**: [LINK TO ANY EXISTING DOCS TO MAINTAIN CONSISTENCY]