chore: cleanup repo and improve docs

.archive/README.md

@@ -0,0 +1,35 @@
+# Archive
+
+This directory contains historical documentation, implementation summaries, and deprecated files that are no longer actively used but kept for reference.
+
+## Contents
+
+### Implementation Summaries
+- Historical implementation documentation from various issues and features
+- Performance testing documentation
+- Accessibility implementation records
+- Testing strategy documents
+
+### PR-Related Files
+- Old PR descriptions and summaries
+- Issue-specific PR templates
+- Historical PR commands and workflows
+
+## Note
+
+These files are archived for historical reference only. For current documentation, please refer to:
+
+- [README.md](../README.md) - Project overview
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+- [DEVELOPMENT.md](../DEVELOPMENT.md) - Development setup
+- [ARCHITECTURE.md](../ARCHITECTURE.md) - System architecture
+- [docs/](../docs/) - Current documentation
+
+## Retention Policy
+
+Files in this archive may be removed after:
+- 1 year from archival date for implementation summaries
+- 6 months for PR-related documentation
+- When no longer referenced by any active documentation
+
+Last updated: 2024

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,112 @@
+# Pull Request
+
+## 📋 Description
+
+Brief description of the changes in this PR.
+
+## 🎯 Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code refactoring
+- [ ] Test addition/update
+- [ ] CI/CD update
+
+## 🔗 Related Issues
+
+Closes #(issue number)
+Relates to #(issue number)
+
+## 📝 Changes Made
+
+- Change 1
+- Change 2
+- Change 3
+
+## 🧪 Testing
+
+### Test Coverage
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] All tests passing locally
+- [ ] Test coverage maintained/improved
+
+### Manual Testing
+- [ ] Tested on testnet
+- [ ] Tested locally
+- [ ] Edge cases tested
+
+**Test Results:**
+```
+[Paste test output or describe manual testing performed]
+```
+
+## 📸 Screenshots (if applicable)
+
+[Add screenshots for UI changes]
+
+## ✅ Checklist
+
+### Code Quality
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex code
+- [ ] No unnecessary console.log or debug code
+- [ ] No commented-out code
+
+### Documentation
+- [ ] Documentation updated (if needed)
+- [ ] API documentation updated (if applicable)
+- [ ] CHANGELOG.md updated
+- [ ] README updated (if needed)
+
+### Testing & Quality
+- [ ] All tests pass (`cargo test`)
+- [ ] No linting errors (`cargo clippy`)
+- [ ] Code formatted (`cargo fmt`)
+- [ ] No new warnings introduced
+- [ ] Gas benchmarks run (if applicable)
+
+### Security
+- [ ] Security implications considered
+- [ ] No sensitive data exposed
+- [ ] Input validation added
+- [ ] Authorization checks in place
+
+### Git
+- [ ] Branch is up to date with main
+- [ ] Commits are atomic and well-described
+- [ ] Commit messages follow convention
+- [ ] No merge conflicts
+
+## 🔍 Reviewer Notes
+
+[Any specific areas you'd like reviewers to focus on]
+
+## 📊 Performance Impact
+
+- [ ] No performance impact
+- [ ] Performance improved
+- [ ] Performance impact acceptable (explain below)
+
+**Details:**
+[Describe any performance implications]
+
+## 🚀 Deployment Notes
+
+[Any special deployment considerations, migration steps, or configuration changes needed]
+
+## 📚 Additional Context
+
+[Add any other context about the PR here]
+
+---
+
+**By submitting this PR, I confirm that:**
+- [ ] I have read and followed the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines
+- [ ] My code follows the project's coding standards
+- [ ] I have tested my changes thoroughly
+- [ ] I am ready for code review

CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to PredictIQ will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive developer onboarding documentation (CONTRIBUTING.md, DEVELOPMENT.md, ARCHITECTURE.md)
+- Repository cleanup and organization
+- Documentation structure in docs/ directory
+- Archive directory for historical documentation
+- Pull request template in .github/
+- CHANGELOG.md for tracking changes
+
+### Changed
+- Reorganized repository structure for better navigation
+- Moved gas optimization docs to docs/gas/
+- Moved security docs to docs/security/
+- Moved quick reference guides to docs/quick-reference/
+- Archived historical implementation summaries
+
+### Fixed
+- Repository root decluttered
+- Documentation hierarchy established
+
+## [1.0.0] - 2024-01-15
+
+### Added
+- Initial release of PredictIQ smart contracts
+- Market creation and management functionality
+- Betting system with odds calculation
+- Oracle integration (Pyth Network and Reflector)
+- Hybrid resolution mechanism (oracle + community voting)
+- Community voting system for disputed markets
+- Dispute resolution mechanism
+- Fee management system
+- Circuit breaker for emergency pause
+- Admin functions for contract management
+- Comprehensive test suite
+- Gas optimization benchmarks
+- Event emission for off-chain indexing
+- Multi-token support
+- Governance module
+
+### Security
+- Role-based access control
+- Input validation on all public functions
+- Reentrancy protection
+- Integer overflow protection
+- Circuit breaker mechanism
+- Monitoring and error tracking
+
+### Documentation
+- README with project overview
+- API specification document
+- Gas optimization guides
+- Security documentation
+- Quick reference guides
+
+## [0.9.0] - 2023-12-01
+
+### Added
+- Beta release for testnet
+- Core market functionality
+- Basic oracle integration
+- Initial test suite
+
+### Known Issues
+- Performance optimization needed
+- Additional oracle providers to be added
+- Governance features in development
+
+---
+
+## Version History
+
+- **[Unreleased]** - Current development
+- **[1.0.0]** - 2024-01-15 - Initial stable release
+- **[0.9.0]** - 2023-12-01 - Beta release
+
+## Links
+
+- [Unreleased]: https://github.com/your-org/predict-iq/compare/v1.0.0...HEAD
+- [1.0.0]: https://github.com/your-org/predict-iq/releases/tag/v1.0.0
+- [0.9.0]: https://github.com/your-org/predict-iq/releases/tag/v0.9.0
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to contribute to this project.
+
+## Versioning
+
+We use [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions
+- **PATCH** version for backwards-compatible bug fixes
+
+## Changelog Guidelines
+
+When adding entries:
+- Add new entries to [Unreleased] section
+- Use categories: Added, Changed, Deprecated, Removed, Fixed, Security
+- Include issue/PR references where applicable
+- Keep descriptions clear and concise
+- Update version links at the bottom

README.md

@@ -48,22 +48,33 @@ make test
 
 ```
 PredictIQ/
+├── .archive/                 # Historical documentation
+├── .github/                  # GitHub templates and workflows
+│   ├── PULL_REQUEST_TEMPLATE.md
+│   └── workflows/
 ├── contracts/
 │   └── predict-iq/           # Main prediction market contract
 │       ├── src/              # Contract source code
 │       └── Makefile          # Build and test commands
 ├── docs/                     # Comprehensive documentation
-│   ├── api/                  # API reference
-│   ├── contracts/            # Contract-specific docs
+│   ├── README.md             # Documentation index
 │   ├── gas/                  # Gas optimization guides
-│   ├── operations/           # Deployment and operations
-│   └── security/             # Security documentation
-├── Cargo.toml                # Workspace configuration
-└── README.md                 # This file
+│   ├── security/             # Security documentation
+│   └── quick-reference/      # Quick reference guides
+├── tests/                    # Test files
+├── README.md                 # This file
+├── CONTRIBUTING.md           # Contribution guidelines
+├── DEVELOPMENT.md            # Development setup guide
+├── ARCHITECTURE.md           # System architecture
+├── API_SPEC.md               # API specification
+├── CHANGELOG.md              # Version history
+└── Cargo.toml                # Workspace configuration
 ```
 
 **Key Components:**
-- **`predict-iq`**: Main prediction market contract with oracle integration, voting, disputes, and governance
+- **`contracts/predict-iq/`**: Main prediction market contract with oracle integration, voting, disputes, and governance
+- **`docs/`**: Organized documentation by category
+- **`.archive/`**: Historical documentation for reference
 
 ---
 
@@ -289,32 +300,39 @@ soroban contract inspect \
 
 ## 📚 Documentation
 
-### Quick Links
+### 🔗 Quick Links
 
-- **[📖 Documentation Index](./docs/README.md)** - Complete documentation overview
-- **[🚀 API Documentation](./docs/api/API_DOCUMENTATION.md)** - Complete API reference and integration guides
-- **[📋 Contract README](./contracts/predict-iq/README.md)** - Detailed contract documentation
+| Document | Description |
+|----------|-------------|
+| **[📖 Documentation Index](./docs/README.md)** | Complete documentation overview |
+| **[🚀 Getting Started](./DEVELOPMENT.md)** | Development setup and workflows |
+| **[🤝 Contributing](./CONTRIBUTING.md)** | Contribution guidelines |
+| **[🏗️ Architecture](./ARCHITECTURE.md)** | System design and architecture |
+| **[📋 API Specification](./API_SPEC.md)** | API reference and integration |
+| **[📝 Changelog](./CHANGELOG.md)** | Version history and changes |
 
-### Documentation Categories
+### Documentation by Category
 
-#### 🔒 Security
-- **[Security Best Practices](./docs/security/SECURITY_BEST_PRACTICES.md)** - Development security guidelines
-- **[Attack Vectors](./docs/security/ATTACK-VECTORS.md)** - Known threats and mitigations
-- **[Audit Checklist](./docs/security/AUDIT_CHECKLIST.md)** - Security audit requirements
-- **[Security Testing Guide](./docs/security/SECURITY_TESTING_GUIDE.md)** - Security testing procedures
+#### 🚀 Getting Started
+- **[Development Guide](./DEVELOPMENT.md)** - Complete setup instructions
+- **[Quick Start](./docs/quick-reference/QUICK_START.md)** - Get up and running quickly
+- **[Contributing Guidelines](./CONTRIBUTING.md)** - How to contribute
+
+#### 🏗️ Architecture & Design
+- **[Architecture Overview](./ARCHITECTURE.md)** - System design and components
+- **[API Specification](./API_SPEC.md)** - Complete API reference
 
 #### ⛽ Gas Optimization
-- **[Gas Optimization](./docs/gas/GAS_OPTIMIZATION.md)** - Optimization strategies
-- **[Gas Cost Analysis](./docs/gas/GAS_COST_ANALYSIS.md)** - Detailed cost breakdown
-- **[Gas Monitoring](./docs/gas/GAS_MONITORING.md)** - Monitoring tools and techniques
-- **[Gas Benchmarking](./docs/gas/GAS_BENCHMARKING.md)** - Performance benchmarks
+- **[Gas Optimization Guide](./docs/gas/GAS_OPTIMIZATION.md)** - Optimization strategies
+- **[Quick Start Gas Optimization](./docs/gas/QUICK_START_GAS_OPTIMIZATION.md)** - Quick tips
 
-#### 🛠️ Operations
-- **[Incident Response](./docs/operations/INCIDENT_RESPONSE.md)** - Incident management procedures
+#### 🔒 Security
+- **[Multisig Emergency Pause](./docs/security/MULTISIG_EMERGENCY_PAUSE.md)** - Emergency controls
+- **[Security Best Practices](./ARCHITECTURE.md#security-architecture)** - Security guidelines
 
-#### 📋 Contracts
-- **[Types System](./docs/contracts/TYPES_SYSTEM.md)** - Data structures and types
-- **[Voting System](./docs/contracts/VOTING_SYSTEM.md)** - Voting and dispute resolution
+#### 📚 Reference
+- **[Quick Reference Guides](./docs/quick-reference/)** - Command references and cheat sheets
+- **[Contract Documentation](./contracts/predict-iq/README.md)** - Detailed contract docs
 
 ---