thebtf · thebtf · Nov 18, 2025 · Nov 18, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -129,7 +129,7 @@ Containerized deployment with Docker Compose:
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this project.
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on contributing to this project.
 
 ## License
 

diff --git a/README.md b/README.md
@@ -119,7 +119,7 @@ docker-compose -f docker-compose.traefik.yml up -d
 # Access at https://chatmock.example.com/webui
 ```
 
-📖 **[Complete Docker Documentation](https://github.com/RayBytes/ChatMock/blob/main/DOCKER.md)** | 🚀 **[Production Guide](./docs/PRODUCTION.md)** | 🔒 **[Traefik Setup](./docs/TRAEFIK.md)**
+📖 **[Complete Docker Documentation](./docs/DOCKER.md)** | 🚀 **[Production Guide](./docs/PRODUCTION.md)** | 🔒 **[Traefik Setup](./docs/TRAEFIK.md)**
 
 # Examples
 
@@ -442,7 +442,7 @@ Complete guides for all aspects of ChatMock:
 - 🎨 **[WebUI Guide](./docs/WEBUI.md)** - Dashboard features and API
 - 🚀 **[Production Deployment](./docs/PRODUCTION.md)** - Performance tuning and scaling
 - 🔒 **[Traefik Integration](./docs/TRAEFIK.md)** - Automatic HTTPS setup
-- 📖 **[Docker Instructions](https://github.com/RayBytes/ChatMock/blob/main/DOCKER.md)** - Docker basics
+- 📖 **[Docker Instructions](./docs/DOCKER.md)** - Docker basics and deployment
 - ⚙️ **[.env Reference](./.env.example)** - All configuration options
 
 # Troubleshooting

diff --git a/ARCHITECTURES.md → docs/ARCHITECTURES.md b/ARCHITECTURES.md → docs/ARCHITECTURES.md
diff --git a/BUILD.md → docs/BUILD.md b/BUILD.md → docs/BUILD.md
diff --git a/CHANGELOG.md → docs/CHANGELOG.md b/CHANGELOG.md → docs/CHANGELOG.md
diff --git a/CONTRIBUTING.md → docs/CONTRIBUTING.md b/CONTRIBUTING.md → docs/CONTRIBUTING.md
diff --git a/CREATE_PR_STEPS.md → docs/CREATE_PR_STEPS.md b/CREATE_PR_STEPS.md → docs/CREATE_PR_STEPS.md
diff --git a/DOCKER.md → docs/DOCKER.md b/DOCKER.md → docs/DOCKER.md
diff --git a/MANUAL_BUILD.md → docs/MANUAL_BUILD.md b/MANUAL_BUILD.md → docs/MANUAL_BUILD.md
diff --git a/PR_DESCRIPTION.md → docs/PR_DESCRIPTION.md b/PR_DESCRIPTION.md → docs/PR_DESCRIPTION.md
diff --git a/docs/README.md b/docs/README.md
@@ -1,215 +1,76 @@
 # ChatMock Documentation
 
-Welcome to the ChatMock documentation! This directory contains comprehensive guides for deploying, configuring, and using ChatMock.
+Welcome to the ChatMock documentation! This directory contains comprehensive guides for all aspects of ChatMock.
 
 ## 📚 Documentation Index
 
 ### Getting Started
-- **[Main README](../README.md)** - Project overview and quick start guide
-- **[.env.example](../.env.example)** - Configuration options reference
-
-### Features
-- **[WEBUI.md](./WEBUI.md)** - Web dashboard documentation
-  - Dashboard overview
-  - Usage statistics and monitoring
-  - Model information
-  - Configuration management
-  - API endpoints
-
-### Deployment
-- **[PRODUCTION.md](./PRODUCTION.md)** - Production deployment guide
-  - Gunicorn configuration
-  - Performance tuning
-  - Scaling strategies
-  - Monitoring and logging
-  - High availability setup
-  - Security best practices
-
-- **[TRAEFIK.md](./TRAEFIK.md)** - Traefik integration guide
-  - Automatic HTTPS with Let's Encrypt
-  - Reverse proxy configuration
-  - Load balancing
-  - Custom middleware
-  - Troubleshooting
+- **[Main README](../README.md)** - Project overview and quick start
+- **[CLAUDE.md](../CLAUDE.md)** - Detailed project description and architecture
 
-## 🚀 Quick Links
-
-### Common Tasks
-
-**Deploy with Docker:**
-```bash
-docker-compose up -d
-```
-
-**Deploy with Traefik (HTTPS):**
-```bash
-docker-compose -f docker-compose.traefik.yml up -d
-```
-
-**Access WebUI:**
-- Local: http://localhost:8000/webui
-- Production: https://your-domain.com/webui
-
-**First-time login:**
-```bash
-docker-compose --profile login up chatmock-login
-```
-
-## 📖 Documentation Structure
-
-```
-docs/
-├── README.md          # This file
-├── WEBUI.md          # Web dashboard guide
-├── PRODUCTION.md     # Production deployment
-└── TRAEFIK.md        # Traefik integration
-```
-
-## 🔧 Configuration
-
-Key configuration files:
-- `.env` - Environment variables (copy from `.env.example`)
-- `gunicorn.conf.py` - Gunicorn server configuration
-- `docker-compose.yml` - Standard Docker deployment
-- `docker-compose.traefik.yml` - Traefik-integrated deployment
-
-## 🆕 New in This Release
-
-### Performance Improvements
-- ✅ **Gunicorn with gevent workers** - 3-5x performance increase
-- ✅ **Concurrent request handling** - Handle 1000+ connections
-- ✅ **Production-ready deployment** - Battle-tested WSGI server
-
-### WebUI Dashboard
-- ✅ **Real-time statistics** - Monitor usage and limits
-- ✅ **Visual analytics** - Charts and progress bars
-- ✅ **Configuration management** - Change settings via UI
-- ✅ **Model browser** - Explore available models
-
-### Traefik Integration
-- ✅ **Automatic HTTPS** - Let's Encrypt certificates
-- ✅ **Reverse proxy** - Production-ready routing
-- ✅ **Load balancing** - Scale horizontally
-- ✅ **Health monitoring** - Automatic health checks
-
-## 🎯 Use Cases
-
-### Development
-Perfect for local development with OpenAI-compatible APIs:
-```bash
-# Start server
-docker-compose up -d
-
-# Use with any OpenAI-compatible client
-curl -X POST http://localhost:8000/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"model": "gpt-5", "messages": [{"role": "user", "content": "Hello!"}]}'
-```
-
-### Production
-Deploy with Traefik for automatic HTTPS:
-```bash
-# Configure domain in .env
-CHATMOCK_DOMAIN=chatmock.example.com
-
-# Deploy
-docker-compose -f docker-compose.traefik.yml up -d
-
-# Access via HTTPS
-curl https://chatmock.example.com/health
-```
-
-### High Availability
-Scale horizontally for high-traffic scenarios:
-```bash
-# Scale to 5 instances
-docker-compose up -d --scale chatmock=5
+### Deployment & Configuration
+- **[DOCKER.md](./DOCKER.md)** - Docker deployment guide with PUID/PGID support
+- **[ARCHITECTURES.md](./ARCHITECTURES.md)** - Multi-architecture Docker support (amd64, arm64, arm/v7, arm/v6, 386)
+- **[MANUAL_BUILD.md](./MANUAL_BUILD.md)** - Manual Docker build instructions and troubleshooting
+- **[BUILD.md](./BUILD.md)** - Building macOS/Windows applications with PyInstaller
 
-# Load balancing handled automatically by Traefik
-```
+### Development & Contributing
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines
+- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
 
-## 🔍 Troubleshooting
+### Release Management
+- **[RELEASE_v1.4.0.md](./RELEASE_v1.4.0.md)** - Release instructions for v1.4.0
+- **[CREATE_PR_STEPS.md](./CREATE_PR_STEPS.md)** - Step-by-step PR creation guide
+- **[PR_DESCRIPTION.md](./PR_DESCRIPTION.md)** - Pull request template
 
-### Common Issues
-
-**WebUI not loading?**
-- Check server is running: `docker-compose ps`
-- Verify port 8000 is accessible
-- Review logs: `docker-compose logs chatmock`
-
-**Performance issues?**
-- Increase Gunicorn workers: `GUNICORN_WORKERS=8`
-- Check resource limits: `docker stats chatmock`
-- See [PRODUCTION.md](./PRODUCTION.md) for tuning guide
-
-**SSL certificate issues?**
-- Verify DNS points to server
-- Check Traefik logs: `docker logs traefik`
-- See [TRAEFIK.md](./TRAEFIK.md) for troubleshooting
-
-## 📊 Performance Benchmarks
-
-With Gunicorn + gevent (4 CPU cores, 8GB RAM):
-
-| Metric | Value |
-|--------|-------|
-| Requests/Second | 200-500+ |
-| Concurrent Connections | 1000+ |
-| Average Latency | 50-80ms |
-| Memory per Worker | ~150MB |
-
-See [PRODUCTION.md](./PRODUCTION.md) for detailed benchmarks.
-
-## 🛡️ Security
-
-Security features:
-- OAuth2 authentication with ChatGPT
-- HTTPS/TLS encryption (with Traefik)
-- Network isolation
-- Resource limits
-- Non-root container execution
-- Secrets management support
-
-See [PRODUCTION.md](./PRODUCTION.md) for security best practices.
-
-## 🤝 Contributing
+## 🚀 Quick Links
 
-Found an issue or want to improve the documentation?
-1. Fork the repository
-2. Make your changes
-3. Submit a pull request
+### For Users
+- [Docker Deployment](./DOCKER.md) - Get started with Docker
+- [Multi-Architecture Support](./ARCHITECTURES.md) - Find your platform
+- [Changelog](./CHANGELOG.md) - See what's new
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+### For Developers
+- [Contributing Guide](./CONTRIBUTING.md) - How to contribute
+- [Building Applications](./BUILD.md) - Create macOS/Windows apps
+- [Manual Build Guide](./MANUAL_BUILD.md) - Build Docker images manually
 
-## 📝 License
+### For Maintainers
+- [Release Process](./RELEASE_v1.4.0.md) - How to create releases
+- [PR Guidelines](./CREATE_PR_STEPS.md) - Pull request workflow
 
-See [LICENSE](../LICENSE) file for license information.
+## 📦 Release v1.4.0 Features
 
-## 🔗 Additional Resources
+This fork includes:
+- ✅ Docker PUID/PGID support for permission management
+- ✅ Multi-architecture Docker images (5 platforms)
+- ✅ Automated macOS DMG builds via GitHub Actions
+- ✅ GitHub Container Registry integration
+- ✅ Comprehensive documentation
+- ✅ GPT-5.1 model support
 
-- **GitHub Repository**: https://github.com/RayBytes/ChatMock
-- **Issue Tracker**: https://github.com/RayBytes/ChatMock/issues
-- **Discussions**: https://github.com/RayBytes/ChatMock/discussions
+## 🔗 External Resources
 
-## 💡 Tips
+- [Original Repository](https://github.com/RayBytes/ChatMock) - RayBytes/ChatMock
+- [GitHub Releases](https://github.com/thebtf/ChatMock/releases) - Download pre-built binaries
+- [Container Registry](https://github.com/thebtf/ChatMock/pkgs/container/chatmock) - Docker images
 
-1. **Start simple**: Use `docker-compose.yml` for local development
-2. **Go production**: Switch to `docker-compose.traefik.yml` for deployment
-3. **Monitor usage**: Check WebUI dashboard regularly
-4. **Tune performance**: Adjust Gunicorn workers based on load
-5. **Enable HTTPS**: Always use Traefik in production
-6. **Scale horizontally**: Add more instances as traffic grows
-7. **Backup data**: Regular backups of `/data` volume
-8. **Update regularly**: Pull latest images for security updates
+## 📝 Documentation Guidelines
 
-## 📧 Support
+When adding new documentation:
+1. Place it in the \`docs/\` directory
+2. Update this README.md with a link
+3. Use clear headings and examples
+4. Include troubleshooting sections
+5. Keep it up to date with code changes
 
-Need help?
-- Check documentation in this directory
-- Search [GitHub Issues](https://github.com/RayBytes/ChatMock/issues)
-- Create a new issue with detailed information
-- Join community discussions
+## 🤝 Contributing to Documentation
 
----
+Documentation improvements are welcome! Please:
+- Follow the existing structure
+- Use Markdown best practices
+- Include code examples where appropriate
+- Test all commands and links
+- Submit PRs with clear descriptions
 
-**Happy deploying! 🚀**
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
diff --git a/RELEASE_v1.4.0.md → docs/RELEASE_v1.4.0.md b/RELEASE_v1.4.0.md → docs/RELEASE_v1.4.0.md
diff --git a/requirements.txt b/requirements.txt
@@ -1,13 +1,13 @@
-blinker==1.8.2
-certifi==2024.8.30
-click==8.1.7
-flask==3.0.3
-gunicorn==22.0.0
-gevent==24.2.1
-idna==3.10
-itsdangerous==2.2.0
-jinja2==3.1.4
-markupsafe==2.1.5
-requests==2.32.3
-urllib3==2.2.3
-werkzeug==3.0.4
+blinker>=1.7.0,<2.0.0
+certifi>=2023.7.0
+click>=8.1.0,<9.0.0
+flask>=3.0.0,<4.0.0
+gunicorn>=22.0.0,<23.0.0
+gevent>=24.2.0,<25.0.0
+idna>=3.4
+itsdangerous>=2.1.0,<3.0.0
+jinja2>=3.1.0,<4.0.0
+markupsafe>=2.1.0,<3.0.0
+requests>=2.31.0,<3.0.0
+urllib3>=2.0.0,<3.0.0
+werkzeug>=3.0.0,<4.0.0