docs: comprehensive README with architecture, agents, and workers

README.md

@@ -1,78 +1,95 @@
-# BlackRoad
+# BlackRoad OS
 
-**Pave Tomorrow.**
+[![Lint](https://git.blackroad.io/blackroad-os/blackroad/actions/workflows/lint.yml/badge.svg)](https://git.blackroad.io/blackroad-os/blackroad/actions)
 
-The one repo. Everything BlackRoad OS in a single place.
+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.
 
-## Structure
+## Architecture
 
 ```
-blackroad/
+┌─────────────────────────────────────────────────────────────────┐
-├── bin/           230 CLI tools and scripts (ask-*, br-*, agent-*, roadid, carpool)
+│                    Cloudflare Edge (8 Workers)                   │
-├── scripts/       99 automation scripts (health, backup, sync, deploy, agents)
+│  roadcode-squad · fleet-dashboard · stats · analytics · roadpay │
-├── fleet/         Node configs, deployment, fleet management
+└─────────────┬───────────────────────────────────────────────────┘
-├── workers/       Cloudflare Worker sources (roadpay, road-search, squad webhooks)
+              │ Cloudflare Tunnels
-├── roadc/         RoadC programming language (lexer, parser, interpreter)
+┌─────────────┴───────────────────────────────────────────────────┐
-├── roadnet/       Mesh network (5 APs, WireGuard, failover, wire-map)
+│                     WireGuard Mesh (10.8.0.x)                    │
-├── operator/      Memory system scripts (journal, codex, TIL, todos, indexer)
+│                                                                  │
-├── config/        System configuration files
+│  Alice (.49)      Cecilia (.96)     Octavia (.101)              │
-├── dotfiles/      Shell configs (.zshrc, .gitconfig, etc.)
+│  Gateway/DNS      Edge AI 26T       Gitea/Docker                │
-├── memory/        Memory system data
+│                                                                  │
-└── docs/          Documentation site source
+│  Aria (.98)       Lucidia (.38)     Anastasia (DO)              │
+│  Orchestration    Memory/Cognition  WG Hub                       │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ## Quick Start
 
 ```bash
-# Add bin to PATH
+make health    # Check all 8 workers
-export PATH="$HOME/blackroad/bin:$PATH"
+make fleet     # Ping all 5 Pi nodes
-
+make sync      # Sync sources into monorepo
-# Fleet health
+make push      # Sync + push to Gitea
-./scripts/blackroad-health-monitor.sh
+make lint      # Lint shell + JS
-
-# Ask an agent
-./bin/ask-alice "check DNS status"
-./bin/ask-cecilia "what models are loaded?"
-
-# RoadC
-cd roadc && python3 roadc.py examples/hello.road
-
-# Deploy a worker
-cd workers && npx wrangler deploy
 ```
 
-## Fleet
+## Structure
 
-| Node | IP | Role |
+| Directory | Contents |
-|------|----|------|
+|-----------|----------|
-| Alice | .49 | Gateway, Pi-hole, 48+ domains |
+| `bin/` | 230+ CLI tools and utilities |
-| Cecilia | .96 | Edge AI, Hailo-8 (26 TOPS) |
+| `scripts/` | 99 automation scripts |
-| Octavia | .101 | Gitea, Docker Swarm leader |
+| `fleet/` | 97 fleet management configs |
-| Aria | .98 | Portainer, Headscale |
+| `workers/` | Cloudflare Worker sources |
-| Lucidia | .38 | Memory, Cognitive core |
+| `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 | Route | Source |
+| Worker | URL | Status |
-|--------|-------|--------|
+|--------|-----|--------|
-| RoadPay | pay.blackroad.io | workers/roadpay-src/ |
+| roadcode-squad | [workers.dev](https://roadcode-squad.amundsonalexa.workers.dev) | v2.0.0 |
-| RoadSearch | search.blackroad.io | workers/road-search-src/ |
+| fleet-dashboard | [workers.dev](https://fleet-dashboard.amundsonalexa.workers.dev) | v1.1.0 |
-| RoadCode Squad | roadcode-squad.workers.dev | workers/roadcode-squad-src/ |
+| stats-blackroad | [workers.dev](https://stats-blackroad.amundsonalexa.workers.dev) | ✅ |
-| Squad Webhook | squad-webhook.workers.dev | workers/squad-webhook-src/ |
+| analytics-blackroad | [workers.dev](https://analytics-blackroad.amundsonalexa.workers.dev) | ✅ |
-| Stats | stats-blackroad.workers.dev | workers/stats-collect.sh |
+| 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) | ✅ |
 
-## Agents
+## License
 
-| Agent | CLI | Role |
+MIT — see [LICENSE](LICENSE)
-|-------|-----|------|
-| 🌐 Alice | `ask-alice` | Gateway & Infrastructure |
-| 🧠 Lucidia | `ask-lucidia` | Memory & Cognition |
-| ⚡ Cecilia | `ask-cecilia` | Edge AI & Inference |
-| 🔌 Cece | `ask-cece` | API Gateway |
-| 🎵 Aria | `ask-aria` | Orchestration |
-| 👁️ Eve | `ask-eve` | Intelligence & Analysis |
-| 🌊 Meridian | `ask-meridian` | Networking & Mesh |
-| 🛡️ Sentinel | `ask-sentinel` | Security & Audit |
 
 ---
-*🛣️ BlackRoad OS — Pave Tomorrow.*
+
+*BlackRoad OS — Pave Tomorrow.*