# 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*