3c976798e9
- Add mission statement and core components table - Add documentation structure with links to new docs - Add repository map for all BlackRoad-OS repos - Add Six Portals overview table - Add implementation status with phase checkboxes - Update quick start and contributing sections 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
# BlackRoad OS Documentation
|
|
|
|
> *The operating system for the AI age — where software adapts to humans, not the other way around.*
|
|
|
|
[](https://docs.blackroad.io)
|
|
[](LICENSE)
|
|
|
|
---
|
|
|
|
## What is BlackRoad OS?
|
|
|
|
BlackRoad OS is a **governance and orchestration platform** for AI agents. It provides:
|
|
|
|
- **Governance Layer** — Policies, audit trails, and permission management for AI operations
|
|
- **Agent Orchestration** — Coordinate multiple AI agents across tools and workflows
|
|
- **Six Portals** — Integrated experiences for personal AI, education, media, gaming, navigation, and privacy
|
|
|
|
### Core Components
|
|
|
|
| Component | Purpose |
|
|
|-----------|---------|
|
|
| **Cece** | Lucidia-class governance agent — the brain of BlackRoad |
|
|
| **Policies** | Rules that allow, deny, or modify AI actions |
|
|
| **Ledger** | Immutable audit trail of all governance events |
|
|
| **Intents** | Task and workflow state management |
|
|
| **Claims & Delegations** | Identity and permission management |
|
|
|
|
---
|
|
|
|
## Documentation Structure
|
|
|
|
### Vision & Strategy
|
|
- [**Manifesto**](docs/meta/vision/manifesto.md) — Why BlackRoad exists
|
|
- [**Vision & Mission**](docs/meta/vision/mission.md) — 5-year roadmap and success metrics
|
|
- [**Architecture**](docs/meta/vision/architecture.md) — System design and component overview
|
|
|
|
### Governance Layer
|
|
- [**Cece Agent Mode**](docs/governance/cece-agent-mode.md) — System prompt for the governance agent
|
|
- [**Governance Roadmap**](docs/governance/governance-roadmap.md) — Sprint plan and implementation details
|
|
|
|
### Technical Reference
|
|
- [**KV Schema**](docs/reference/kv-schema.md) — Data model for governance objects
|
|
- [**API Design**](docs/reference/api-design.md) — REST API specification
|
|
|
|
### Operations
|
|
- [Getting Started](docs/getting-started/) — Quick start guides
|
|
- [Runbooks](docs/runbooks/) — Operational procedures
|
|
- [Platform Guides](docs/platform-guides/) — Deployment and configuration
|
|
|
|
---
|
|
|
|
## Repository Map
|
|
|
|
| Repo | Purpose |
|
|
|------|---------|
|
|
| `blackroad-os-docs` | Documentation (this repo) |
|
|
| `blackroad-os-core` | Desktop UI, auth, identity |
|
|
| `blackroad-os-api` | API gateway, REST endpoints |
|
|
| `blackroad-os-operator` | Job scheduler, background workers |
|
|
| `blackroad-os-agents` | Agent implementations |
|
|
| `blackroad-os-infra` | IaC, deployment configs |
|
|
| `blackroad-os-web` | Web frontend |
|
|
| `blackroad-os-prism-console` | Admin dashboard |
|
|
| `lucidia-core` | AI reasoning engines |
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20+ (see `package.json` engines)
|
|
- npm or pnpm for dependency management
|
|
|
|
### Running locally
|
|
|
|
```bash
|
|
npm install
|
|
npm run start
|
|
```
|
|
|
|
The dev server runs at http://localhost:3000.
|
|
|
|
### Building for production
|
|
|
|
```bash
|
|
npm run build
|
|
npm run serve
|
|
```
|
|
|
|
---
|
|
|
|
## The Six Portals
|
|
|
|
| Portal | Domain | Description |
|
|
|--------|--------|-------------|
|
|
| **Lucidia** | Personal AI | Your AI that actually knows you — persistent memory, learned preferences |
|
|
| **RoadWork** | Education | Adaptive learning that evolves with your understanding |
|
|
| **RoadView** | Media | Video and image creation without the learning curve |
|
|
| **RoadGlitch** | Gaming | Games that evolve with your play style |
|
|
| **RoadWorld** | Navigation | Context-aware guidance with local knowledge |
|
|
| **BackRoad** | Privacy | Security and anonymization as infrastructure |
|
|
|
|
---
|
|
|
|
## Implementation Status
|
|
|
|
### Phase 1: Foundation (Current)
|
|
- [x] Governance layer specification
|
|
- [x] KV schema design
|
|
- [x] API design
|
|
- [ ] Core implementation
|
|
- [ ] Agent bootstrap
|
|
|
|
### Phase 2: Portals
|
|
- [ ] Lucidia MVP
|
|
- [ ] RoadWork prototype
|
|
- [ ] RoadView alpha
|
|
|
|
### Phase 3: Ecosystem
|
|
- [ ] Developer SDK
|
|
- [ ] Agent marketplace
|
|
- [ ] Enterprise features
|
|
|
|
See [IMPLEMENTATION-ROADMAP.md](docs/IMPLEMENTATION-ROADMAP.md) for full task tracking.
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
Keep content concise, link across sections, and prefer iterative updates over monolithic rewrites. Mark components as `planned`, `alpha`, or `in-flight` when appropriate so operators, developers, and partners have an honest view of the system.
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for style conventions, validation steps, and how to extend the sidebar when adding new pages.
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- **Website:** [blackroad.io](https://blackroad.io)
|
|
- **Docs:** [docs.blackroad.io](https://docs.blackroad.io)
|
|
- **GitHub:** [github.com/BlackRoad-OS](https://github.com/BlackRoad-OS)
|
|
|
|
---
|
|
|
|
*The road is long. The road is black. But we're building it together.*
|