Merge commit 'b079c8e1a61144b24fccb8cd1e85d99a5492b0ad'

codex-docs/docs/index.md

@@ -93,3 +93,183 @@ BlackRoad Operating System is licensed under the MIT License.
 ---
 
 **Built with ❤️ by the BlackRoad OS Team**
+# BlackRoad OS Codex
+
+**Welcome to the BlackRoad Operating System Documentation**
+
+BlackRoad OS is a Windows 95-inspired web-based operating system that brings together AI orchestration, blockchain technology, and a nostalgic user interface. This is the complete technical documentation for developers, operators, and contributors.
+
+---
+
+## 🚀 Quick Links
+
+<div class="grid cards" markdown>
+
+- **[Quick Start →](guides/quickstart.md)**
+
+    Get up and running with BlackRoad OS in minutes
+
+- **[Architecture Overview →](architecture/overview.md)**
+
+    Understand the system design and components
+
+- **[API Reference →](api/overview.md)**
+
+    Explore the complete API documentation
+
+- **[Deployment Guide →](guides/deployment.md)**
+
+    Deploy BlackRoad OS to production
+
+</div>
+
+---
+
+## 📚 What is BlackRoad OS?
+
+BlackRoad Operating System is a complete AI-powered ecosystem that includes:
+
+- **🖥️ Pocket OS**: A browser-based operating system with a Windows 95-inspired interface
+- **🌌 Prism Console**: Administrative interface for job queue management, event logging, and system metrics
+- **🤖 Agent Library**: 200+ autonomous AI agents across 10 categories
+- **🔗 RoadChain**: Blockchain-based audit trail and provenance system
+- **🔐 PS-SHA∞ Identity**: Sovereign identity system for agents and users
+- **☁️ CloudWay**: Infrastructure automation and deployment orchestration
+
+---
+
+## 🎯 Core Philosophy
+
+**Agent-First**
+:   Humans orchestrate, agents execute. BlackRoad OS is designed for AI-driven workflows.
+
+**Memory-Conscious**
+:   Everything is logged and retrievable. Complete audit trails for compliance and debugging.
+
+**Ledger-Aware**
+:   Critical actions are provable and tamper-evident via RoadChain.
+
+**Zero-Dependency Frontend**
+:   Vanilla JavaScript with no build process. Fast, simple, and maintainable.
+
+**Cloud-Native**
+:   Infrastructure as software. Deployed on Railway with Cloudflare CDN.
+
+---
+
+## 🗺️ Documentation Map
+
+### For Developers
+
+- **[Quick Start Guide](guides/quickstart.md)**: Get started in 5 minutes
+- **[Development Setup](guides/development.md)**: Set up your local environment
+- **[API Reference](api/overview.md)**: Complete API documentation
+- **[Creating Agents](agents/creating-agents.md)**: Build your own agents
+
+### For Operators
+
+- **[Deployment Guide](guides/deployment.md)**: Production deployment steps
+- **[Environment Variables](guides/environment-variables.md)**: Configuration reference
+- **[Infrastructure & Deployment](architecture/infra-deployment.md)**: Railway + Cloudflare setup
+
+### For Contributors
+
+- **[Contributing Guide](contributing.md)**: How to contribute to BlackRoad OS
+- **[Architecture Overview](architecture/overview.md)**: System architecture deep dive
+
+---
+
+## 🏗️ Current Status: Phase 2.5
+
+**Infrastructure Wiring Complete**
+
+BlackRoad OS Phase 2.5 has completed the infrastructure wiring, including:
+
+- ✅ Monorepo as canonical OS home
+- ✅ Prism Console served at `/prism`
+- ✅ Documentation via GitHub Pages
+- ✅ Railway + Cloudflare deployment ready
+- ✅ Comprehensive environment variable management
+
+**What's Next: Phase 2.6+**
+
+- 🔄 Full Prism Console functionality (job queue, event log, metrics)
+- 🔄 Agent orchestration workflows
+- 🔄 RoadChain integration
+- 🔄 PS-SHA∞ identity system
+
+See [Phase 2.5 Decisions](architecture/phase2-decisions.md) for details.
+
+---
+
+## 🌟 Key Features
+
+### Prism Console
+
+Administrative interface for managing the entire BlackRoad ecosystem:
+
+- **Job Queue**: Monitor and manage long-running tasks
+- **Event Log**: Real-time system event stream
+- **Metrics Dashboard**: System health and performance
+- **Agent Management**: View and control 200+ AI agents
+
+Access: `https://blackroad.systems/prism`
+
+### Agent Library
+
+200+ autonomous AI agents across 10 categories:
+
+- DevOps (30+ agents)
+- Engineering (40+ agents)
+- Data Science (25+ agents)
+- Security (20+ agents)
+- Finance (15+ agents)
+- Creative (20+ agents)
+- Business (15+ agents)
+- Research (15+ agents)
+- Web (15+ agents)
+- AI/ML (15+ agents)
+
+Learn more: [Agent Overview](agents/overview.md)
+
+### RoadChain
+
+Blockchain-based audit trail:
+
+- Tamper-evident logging
+- Provenance tracking
+- Compliance-ready
+- SHA-256 hashing
+
+API: `/api/blockchain`
+
+---
+
+## 🚀 Production URLs
+
+| Service | URL | Description |
+|---------|-----|-------------|
+| **Main OS** | https://blackroad.systems | BlackRoad OS desktop interface |
+| **Prism Console** | https://blackroad.systems/prism | Administrative console |
+| **API Documentation** | https://blackroad.systems/api/docs | OpenAPI/Swagger docs |
+| **Codex (this site)** | https://docs.blackroad.systems | Complete documentation |
+
+---
+
+## 🤝 Community & Support
+
+- **GitHub**: [blackboxprogramming/BlackRoad-Operating-System](https://github.com/blackboxprogramming/BlackRoad-Operating-System)
+- **Issues**: Report bugs and request features on GitHub Issues
+- **Discord**: Coming in Phase 1 Q2 (community hub)
+
+---
+
+## 📄 License
+
+BlackRoad Operating System is proprietary software. See the repository LICENSE file for details.
+
+---
+
+**Where AI meets the open road.** 🛣️
+
+*Built with ❤️ by the BlackRoad team*