📁 Reorganize Documentation into Structured docs/ Folder

README.md

@@ -28,34 +28,27 @@ This repository contains smart contracts for Stellar's Soroban platform, organiz
 
 ---
 
-## 📚 API Documentation
+## 📚 Documentation
 
-For comprehensive API documentation, including versioning information, integration examples, and troubleshooting guides, please refer to:
+For comprehensive documentation, please refer to our organized documentation structure:
 
-**📖 [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)**
+**📖 [Documentation Index](./docs/README.md)**
 
-This dedicated documentation file contains:
-- **API Versioning**: Semantic versioning, compatibility matrix, upgrade strategies
-- **Core API Reference**: Function signatures, parameters, and examples
-- **Data Structures**: Complete type definitions and usage
-- **Error Codes**: Comprehensive error reference with solutions
-- **Integration Examples**: Real-world usage patterns and best practices
-- **Troubleshooting Guide**: Common issues and debugging tools
-- **Support Resources**: Community channels and getting help
+### 🚀 API Documentation
+Complete API reference and integration guides: **[API Documentation](./docs/api/API_DOCUMENTATION.md)**
 
----
+### ⛽ Gas Optimization
+Performance optimization and cost analysis: **[Gas Documentation](./docs/gas/)**
+
+### 🔒 Security
+Security audits, best practices, and threat analysis: **[Security Documentation](./docs/security/)**
 
-## ⚡ Gas Optimization Documentation
+### 🛠️ Operations
+Deployment, maintenance, and incident management: **[Operations Documentation](./docs/operations/)**
+
+---
 
-- Gas Guide and Best Practices: [GAS_OPTIMIZATION.md](./GAS_OPTIMIZATION.md)
-- Per-Function Cost Analysis (catalog + templates): [GAS_COST_ANALYSIS.md](./GAS_COST_ANALYSIS.md)
-- Benchmarking Procedures: [GAS_BENCHMARKING.md](./GAS_BENCHMARKING.md)
-- Testing Guidelines (prevent regressions): [GAS_TESTING_GUIDELINES.md](./GAS_TESTING_GUIDELINES.md)
-- Usage Monitoring & Ops: [GAS_MONITORING.md](./GAS_MONITORING.md)
-- Case Studies (Predictify-specific): [GAS_CASE_STUDIES.md](./GAS_CASE_STUDIES.md)
-- Troubleshooting Guide: [GAS_TROUBLESHOOTING.md](./GAS_TROUBLESHOOTING.md)
 
-These documents provide practical steps to measure, monitor, and reduce fees for Soroban contracts in this repo.
 
 ---
 

docs/README.md

@@ -0,0 +1,79 @@
+# 📚 Predictify Contracts Documentation
+
+Welcome to the Predictify Contracts documentation! This directory contains comprehensive documentation for the Predictify Hybrid prediction market smart contract system.
+
+## 📁 Documentation Structure
+
+### 🚀 [API Documentation](./api/API_DOCUMENTATION.md)
+Complete API reference for the Predictify Hybrid contract, including:
+- Contract functions and their parameters
+- Return types and error handling
+- Integration examples
+- Client usage patterns
+
+### 🔒 [Security Documentation](./security/)
+Comprehensive security documentation and guidelines:
+
+- **[Attack Vectors](./security/ATTACK-VECTORS.md)** - Known attack vectors and mitigation strategies
+- **[Audit Checklist](./security/AUDIT_CHECKLIST.md)** - Security audit requirements and checklist
+- **[Security Best Practices](./security/SECURITY_BEST_PRACTICES.md)** - Development and deployment security guidelines
+- **[Security Considerations](./security/SECURITY_CONSIDERATIONS.md)** - Important security considerations for the system
+- **[Security Testing Guide](./security/SECURITY_TESTING_GUIDE.md)** - Security testing procedures and tools
+
+### ⛽ [Gas Optimization Documentation](./gas/)
+Complete gas optimization and cost analysis:
+
+- **[Gas Benchmarking](./gas/GAS_BENCHMARKING.md)** - Performance benchmarks and metrics
+- **[Gas Case Studies](./gas/GAS_CASE_STUDIES.md)** - Real-world gas optimization examples
+- **[Gas Cost Analysis](./gas/GAS_COST_ANALYSIS.md)** - Detailed cost breakdown and analysis
+- **[Gas Monitoring](./gas/GAS_MONITORING.md)** - Tools and techniques for monitoring gas usage
+- **[Gas Optimization](./gas/GAS_OPTIMIZATION.md)** - Strategies and best practices for gas optimization
+- **[Gas Testing Guidelines](./gas/GAS_TESTING_GUIDELINES.md)** - Testing procedures for gas optimization
+- **[Gas Troubleshooting](./gas/GAS_TROUBLESHOOTING.md)** - Common gas-related issues and solutions
+
+### 🛠️ [Operations Documentation](./operations/)
+Operational procedures and incident management:
+
+- **[Incident Response](./operations/INCIDENT_RESPONSE.md)** - Incident response procedures and protocols
+
+### 📋 [Contract Documentation](./contracts/)
+Implementation-specific documentation for the Predictify Hybrid contract:
+
+- **[Types System](./contracts/TYPES_SYSTEM.md)** - Comprehensive type system and data structures
+- **[Voting System](./contracts/VOTING_SYSTEM.md)** - Voting mechanism and dispute resolution
+
+## 🎯 Quick Start
+
+1. **For Developers**: Start with [API Documentation](./api/API_DOCUMENTATION.md)
+2. **For Contract Contributors**: Review [Contract Documentation](./contracts/)
+3. **For Security Auditors**: Review [Security Documentation](./security/)
+4. **For Gas Optimization**: Check [Gas Optimization](./gas/GAS_OPTIMIZATION.md)
+5. **For Operations**: Read [Incident Response](./operations/INCIDENT_RESPONSE.md)
+
+## 🔗 Related Resources
+
+- **[Main Project README](../README.md)** - Project overview and setup instructions
+- **[Contracts Directory](../contracts/)** - Source code for all smart contracts
+- **[GitHub Repository](https://github.com/your-org/predictify-contracts)** - Source code repository
+
+## 📝 Contributing to Documentation
+
+When adding new documentation:
+
+1. **Choose the appropriate category** based on the content type
+2. **Follow the naming convention** (UPPERCASE_WITH_UNDERSCORES.md)
+3. **Update this index** to include the new document
+4. **Add cross-references** to related documents where appropriate
+
+## 🏷️ Documentation Categories
+
+- **API**: Contract interfaces, function references, and integration guides
+- **Contracts**: Implementation-specific documentation for contract systems
+- **Security**: Security audits, best practices, and threat analysis
+- **Gas**: Performance optimization, cost analysis, and monitoring
+- **Operations**: Deployment, maintenance, and incident management
+
+---
+
+*Last updated: $(date)*
+*For questions or suggestions about documentation, please open an issue in the repository.* 

API_DOCUMENTATION.md → docs/api/API_DOCUMENTATION.md

@@ -216,7 +216,7 @@ const getContractVersion = async (contractId: string): Promise<string> => {
 **Documentation:**
 - [v1.0.x API Reference](./docs/api/v1.0/)
 - [v0.9.x Legacy Docs](./docs/api/v0.9/)
-- [Migration Guide v0.9 → v1.0](./docs/migration/v0.9-to-v1.0.md)
+- [Migration Guide v0.9 → v1.0](./migration/v0.9-to-v1.0.md)
 
 **Contract Addresses:**
 - **v1.0.x Mainnet**: `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAHHAGK3HGU`