# BlackRoad OS

[![Lint](https://git.blackroad.io/blackroad-os/blackroad/actions/workflows/lint.yml/badge.svg)](https://git.blackroad.io/blackroad-os/blackroad/actions)

A distributed operating system running on edge hardware — 5 Raspberry Pi 5 nodes, 2 cloud droplets, 8 Cloudflare Workers, and 52 TOPS of edge AI.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    Cloudflare Edge (8 Workers)                   │
│  roadcode-squad · fleet-dashboard · stats · analytics · roadpay │
└─────────────┬───────────────────────────────────────────────────┘
              │ Cloudflare Tunnels
┌─────────────┴───────────────────────────────────────────────────┐
│                     WireGuard Mesh (10.8.0.x)                    │
│                                                                  │
│  Alice (.49)      Cecilia (.96)     Octavia (.101)              │
│  Gateway/DNS      Edge AI 26T       Gitea/Docker                │
│                                                                  │
│  Aria (.98)       Lucidia (.38)     Anastasia (DO)              │
│  Orchestration    Memory/Cognition  WG Hub                       │
└──────────────────────────────────────────────────────────────────┘
```

## Quick Start

```bash
make health    # Check all 8 workers
make fleet     # Ping all 5 Pi nodes
make sync      # Sync sources into monorepo
make push      # Sync + push to Gitea
make lint      # Lint shell + JS
```

## Structure

| Directory | Contents |
|-----------|----------|
| `bin/` | 230+ CLI tools and utilities |
| `scripts/` | 99 automation scripts |
| `fleet/` | 97 fleet management configs |
| `workers/` | Cloudflare Worker sources |
| `roadc/` | RoadC language (lexer/parser/interpreter) |
| `roadnet/` | Mesh network configs |
| `operator/` | Memory system scripts |
| `config/` | System configurations |
| `dotfiles/` | Shell configs |
| `docs/` | Documentation site |

## RoadCode Squad

8 AI agents automatically respond to issues and PRs:

| Agent | Role | Trigger |
|-------|------|---------|
| 🌐 Alice | Gateway & Infrastructure | `@alice` or DNS/routing keywords |
| 🧠 Lucidia | Memory & Cognition | `@lucidia-agent` or memory/AI keywords |
| ⚡ Cecilia | Edge AI & Inference | `@cecilia` or model/inference keywords |
| 🔌 Cece | API Gateway | `@cece` or API/webhook keywords |
| 🎵 Aria | Orchestration | `@aria` or Docker/deploy keywords |
| 👁️ Eve | Intelligence & Analysis | Always responds (analysis) |
| 🌊 Meridian | Networking & Mesh | `@meridian` or WireGuard/mesh keywords |
| 🛡️ Sentinel | Security & Audit | Always responds (security review) |

### Slash Commands

| Command | Action |
|---------|--------|
| `/status` | Fleet health overview |
| `/squad` | List all agents |
| `/assign @agent` | Assign agent to issue |
| `/priority high\|medium\|low` | Set priority label |
| `/help` | Show commands |

## Workers

| Worker | URL | Status |
|--------|-----|--------|
| roadcode-squad | [workers.dev](https://roadcode-squad.amundsonalexa.workers.dev) | v2.0.0 |
| fleet-dashboard | [workers.dev](https://fleet-dashboard.amundsonalexa.workers.dev) | v1.1.0 |
| stats-blackroad | [workers.dev](https://stats-blackroad.amundsonalexa.workers.dev) | ✅ |
| analytics-blackroad | [workers.dev](https://analytics-blackroad.amundsonalexa.workers.dev) | ✅ |
| roadpay | [pay.blackroad.io](https://pay.blackroad.io) | v1.0.0 |
| road-search | [workers.dev](https://road-search.amundsonalexa.workers.dev) | ✅ |
| blackroad-stripe | [workers.dev](https://blackroad-stripe.amundsonalexa.workers.dev) | ✅ |
| squad-webhook | [workers.dev](https://squad-webhook.amundsonalexa.workers.dev) | ✅ |

## License

MIT — see [LICENSE](LICENSE)

---

*BlackRoad OS — Pave Tomorrow.*
