diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e82b3ab --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,244 @@ +# CLAUDE.md - BlackRoad OS Bridge Repository + +## What This Repository Is + +This is **BlackRoad-OS/.github** ("The Bridge") - the central nervous system for a 15-organization AI routing ecosystem. It coordinates infrastructure, documentation, prototypes, blueprints, and interactive pixel worlds for the BlackRoad platform. + +**Core Thesis:** BlackRoad is a routing company, not an AI company. It routes to intelligence (Claude, GPT, Llama, local models) rather than building its own. + +--- + +## Repository Structure + +``` +.github/ +├── CLAUDE.md # This file - AI assistant guide +├── README.md # Org landing page +├── INDEX.md # Browsable table of contents +├── MEMORY.md # Persistent session memory across conversations +├── SIGNALS.md # Morse-code style coordination protocol +├── STREAMS.md # Data flow patterns (upstream/instream/downstream) +├── REPO_MAP.md # Ecosystem architecture diagram +├── BLACKROAD_ARCHITECTURE.md # Core thesis, business model, infrastructure +├── .STATUS # Real-time ecosystem state beacon +│ +├── CECE_ABILITIES.md # AI partner (Cece/Claude) abilities manifest +├── CECE_PROTOCOLS.md # Decision frameworks, escalation, PCDEL loop +│ +├── blackroad-pixel/ # Interactive pixel art UI & games +│ ├── index.html # Desktop OS simulation (main UI) +│ ├── style.css # Retro pixel styling +│ ├── app.js # Desktop interactivity +│ └── games/ # Pixel game worlds +│ ├── index.html # Game hub / launcher +│ ├── stardew/index.html # BlackRoad Harvest (farming sim) +│ ├── pokemon/index.html # BlackRoad Creatures (RPG) +│ ├── webkinz/index.html # BlackRoad Pets (virtual pet world) +│ └── mario/index.html # BlackRoad Runner (platformer) +│ +├── orgs/ # 15 organization blueprints +│ ├── BlackRoad-OS/ # Core infrastructure +│ ├── BlackRoad-AI/ # Intelligence routing +│ ├── BlackRoad-Cloud/ # Edge compute +│ ├── BlackRoad-Hardware/ # Pi cluster + IoT +│ ├── BlackRoad-Foundation/ # CRM & business +│ ├── BlackRoad-Labs/ # R&D experiments +│ ├── BlackRoad-Security/ # Zero-trust & vault +│ ├── BlackRoad-Media/ # Content & publishing +│ ├── BlackRoad-Interactive/ # Games & metaverse +│ ├── BlackRoad-Education/ # Learning platform +│ ├── BlackRoad-Gov/ # Civic tech +│ ├── BlackRoad-Archive/ # Preservation +│ ├── BlackRoad-Studio/ # Design tools +│ ├── BlackRoad-Ventures/ # Business & investments +│ └── Blackbox-Enterprises/ # Enterprise stealth +│ +├── prototypes/ # Working Python code +│ ├── cece-engine/ # Autonomous task processing (PCDEL loop) +│ ├── operator/ # AI request routing engine +│ ├── metrics/ # KPI dashboard +│ ├── control-plane/ # Unified control interface +│ ├── explorer/ # Ecosystem browser +│ ├── dispatcher/ # Event dispatching +│ ├── mcp-server/ # MCP protocol server +│ └── webhooks/ # Webhook handlers (GitHub, Stripe, etc.) +│ +├── templates/ # Integration templates +│ ├── ai-router/ # Multi-provider AI routing +│ ├── salesforce-sync/ # CRM synchronization +│ ├── stripe-billing/ # Payment processing +│ ├── cloudflare-workers/ # Edge compute +│ ├── gdrive-sync/ # Google Drive +│ ├── github-ecosystem/ # GitHub Actions +│ └── design-tools/ # Figma + Canva +│ +├── nodes/ # Hardware node configurations +│ ├── cecilia.yaml # Mac dev machine +│ ├── lucidia.yaml # Pi 5 + Hailo-8 +│ ├── octavia.yaml # Pi 5 + Hailo-8 +│ ├── aria.yaml # Pi 5 agent orchestration +│ ├── alice.yaml # Pi 400 Kubernetes +│ └── shellfish.yaml # Digital Ocean droplet +│ +├── routes/ # Request routing registry +│ └── registry.yaml # Complete routing rules +│ +├── .github/workflows/ # 13 GitHub Actions workflows +│ ├── ci.yml # Continuous integration +│ ├── cece-auto.yml # Autonomous Cece engine +│ ├── intelligent-auto-pr.yml # Auto PR generation +│ ├── self-healing-master.yml # Error recovery +│ └── ... # Health, triage, deploy, etc. +│ +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md +├── SECURITY.md +├── LICENSE # Proprietary BlackRoad OS, Inc. +└── TODO.md +``` + +--- + +## Key Conventions + +### Language & Stack +- **Documentation:** Markdown (majority of repo) +- **Prototypes:** Python (FastAPI-style, CLI tools) +- **UI/Games:** Vanilla HTML5, CSS3, JavaScript (no frameworks) +- **Config:** YAML (node configs, routing registry) +- **CI/CD:** GitHub Actions +- **Fonts:** Press Start 2P (pixel), JetBrains Mono (code) + +### Naming Conventions +- Organization dirs: PascalCase with hyphens (`BlackRoad-AI/`) +- Python files: snake_case (`control_plane/bridge.py`) +- YAML configs: lowercase (`registry.yaml`) +- Markdown docs: UPPER_SNAKE for root docs (`MEMORY.md`), README.md for subdirs +- CSS: BEM-like with kebab-case (`.chat-panel`, `.thumb-item`) + +### Coding Style +- **Python:** Standard lib preferred, CLI via argparse, async where needed +- **JavaScript:** Vanilla JS, no build tools, `const`/`let` only, canvas for games +- **CSS:** CSS custom properties for theming, mobile-responsive, dark theme default +- **Games:** Single HTML files with embedded CSS/JS for portability + +### Design System +``` +Colors: + --bg-dark: #0d0d1a + --bg-panel: #1a1a2e + --accent-pink: #ff6b9d (primary brand) + --accent-purple: #c44dff (secondary) + --accent-cyan: #00d4ff (highlights) + --accent-orange: #f5a623 (warnings/coins) + --accent-green: #7ed321 (success/health) + --accent-red: #d0021b (errors) + +Gradients: + Warm: #ff6b35 → #f7c948 → #ff6b9d → #c44dff + Cool: #4a90d9 → #00d4ff → #7ed321 → #4a90d9 +``` + +--- + +## Development Workflows + +### Adding New Pixel Game Worlds +1. Create directory under `blackroad-pixel/games//` +2. Build as single `index.html` with embedded CSS/JS (canvas-based) +3. Include title screen, HUD, game loop via `requestAnimationFrame` +4. Use BlackRoad color palette and Press Start 2P font +5. Add card entry to `blackroad-pixel/games/index.html` hub + +### Adding New Organization Blueprints +1. Create directory under `orgs//` +2. Include `README.md` (purpose, repos, team), `REPOS.md` (repo list), `SIGNALS.md` (signals) +3. Follow the existing 3-file structure from other orgs + +### Adding New Prototypes +1. Create directory under `prototypes//` +2. Include `README.md`, `__init__.py`, `cli.py` (entry point) +3. Use `requirements.txt` for dependencies +4. Follow the PCDEL pattern if it involves autonomous processing + +### Working with Memory +- `MEMORY.md` persists context across sessions - always read it first +- `.STATUS` is the real-time state beacon - update it after significant changes +- `SIGNALS.md` defines the communication protocol between orgs + +--- + +## AI Assistant Guidelines + +### Session Startup +1. Read `MEMORY.md` for context from previous sessions +2. Read `.STATUS` for current ecosystem state +3. Check `TODO.md` for pending tasks +4. Identify which organization/area the current task belongs to + +### Decision Authority +- **FULL_AUTO:** Code formatting, documentation updates, test runs, CI fixes, routine commits +- **SUGGEST:** Architecture changes, new integrations, prototype design, cross-org coordination +- **ASK_FIRST:** Spending money, external API calls, production deployments, security changes, deleting files + +### Key Relationships +- **Alexa Louise** = founder/CEO +- **Cece/Cecilia** = AI partner (Claude) living in the Bridge +- **12 named agents** in the chat panel each map to different system capabilities +- The **Pi cluster** (lucidia, octavia, aria, alice) are physical hardware nodes + +### What NOT to Do +- Do not modify `LICENSE` without explicit permission +- Do not push to main without review for production-impacting changes +- Do not introduce external JS/CSS frameworks into the pixel UI (vanilla only) +- Do not create files outside the established directory structure +- Do not modify node YAML configs without understanding the hardware topology + +--- + +## Pixel Game Worlds Reference + +| Game | Inspired By | Features | +|------|-------------|----------| +| **BlackRoad Harvest** | Stardew Valley | Farming, seasons, crops, shop, day/night, energy system | +| **BlackRoad Creatures** | Pokemon | 8 creatures, type matchups, battles, capture, leveling, overworld exploration | +| **BlackRoad Pets** | Webkinz | 6 pet types, 5 rooms, feeding/playing/washing, shop, coin minigame, decor | +| **BlackRoad Runner** | Mario | 3 worlds, platforming physics, enemies, power-ups, coins, question blocks | + +All games are self-contained HTML files using Canvas API and can be served from any static host. + +--- + +## Infrastructure Summary + +| Layer | Tech | Cost | +|-------|------|------| +| CDN/Edge | Cloudflare Workers | Free tier | +| CRM | Salesforce | Dev tier | +| Code | GitHub Enterprise | Included | +| Mesh | Tailscale VPN | Free tier | +| Gateway | Digital Ocean droplet | ~$6/mo | +| Hardware | 4x Raspberry Pi + Mac | Owned | +| **Total** | | **~$40/month** | + +--- + +## Quick Commands + +```bash +# Serve pixel UI locally +cd blackroad-pixel && python3 -m http.server 8080 + +# Run a prototype +cd prototypes/operator && python3 -m cli + +# Check ecosystem health +cat .STATUS + +# View routing registry +cat routes/registry.yaml +``` + +--- + +*Last updated: 2026-02-03 | Session: claude/claude-md* diff --git a/blackroad-pixel/games/index.html b/blackroad-pixel/games/index.html new file mode 100644 index 0000000..d9cff9b --- /dev/null +++ b/blackroad-pixel/games/index.html @@ -0,0 +1,195 @@ + + + + + +BlackRoad Pixel Worlds - Game Hub + + + +
+ ← Back to Desktop + +
+ +

THE BLACKROAD GAMING UNIVERSE

+
+
+
+ +
+ + +
+
+
\uD83C\uDF3E\uD83C\uDFE1
+ FARM SIM +
+
+

BLACKROAD HARVEST

+

Plant crops, tend your farm, sell at market. Full day/night cycle, seasons, shop, and 5 crop types.

+
+ FarmingSeasonsTradingCrafting +
+
PLAY NOW
+
+ + + + +
+
+
\u26A1\uD83D\uDD2E
+ PIXEL RPG +
+
+

BLACKROAD CREATURES

+

Explore, battle, and capture 8 unique creatures. Type matchups, leveling, wild encounters on routes.

+
+ RPGBattlesCaptureExplore +
+
PLAY NOW
+
+ + + + +
+
+
\uD83D\uDC31\uD83D\uDC36
+ VIRTUAL PET +
+
+

BLACKROAD PETS

+

Adopt a pet, decorate rooms, feed and play. 6 pet types, 5 rooms, shop, and a coin-earning minigame.

+
+ Virtual PetDecorateMinigamesShop +
+
PLAY NOW
+
+ + + + +
+
+
\uD83C\uDF1F\uD83C\uDF44
+ PLATFORMER +
+
+

BLACKROAD RUNNER

+

Run, jump, stomp enemies across 3 worlds. Power-ups, coins, question blocks, and boss flagpoles.

+
+ PlatformerAction3 WorldsPower-ups +
+
PLAY NOW
+
+ +
+ +
+

© 2026 BlackRoad OS, Inc. | Desktop | All Rights Reserved

+
+
+ + diff --git a/blackroad-pixel/games/mario/index.html b/blackroad-pixel/games/mario/index.html new file mode 100644 index 0000000..29994de --- /dev/null +++ b/blackroad-pixel/games/mario/index.html @@ -0,0 +1,2159 @@ + + + + + +BlackRoad Runner - Pixel Platformer + + + +
+ +
+ COINS: 0 + SCORE: 0 + WORLD 1-1 + LIVES: 3 + TIME: 400 +
+
+
+

GAME OVER

+

Score: 0

+ +
+
+

BLACKROAD RUNNER

+

A Pixel Platformer

+

A/D or LEFT/RIGHT - Move

+

W/UP/SPACE - Jump (hold for higher)

+

SHIFT - Sprint

+

X - Shoot Fireball (with Fire Flower)

+

DOWN on Pipe - Enter Warp

+

5 Worlds - Stomp enemies, collect coins!

+

Hit ? blocks for power-ups!

+ +
+
+ + + + diff --git a/blackroad-pixel/games/pokemon/index.html b/blackroad-pixel/games/pokemon/index.html new file mode 100644 index 0000000..bdad23c --- /dev/null +++ b/blackroad-pixel/games/pokemon/index.html @@ -0,0 +1,1466 @@ + + + + + +BlackRoad Creatures - Pixel RPG + + + +
+ +
+ NEON TOWN + Steps: 0 + $500 +
+
+ +
+ +
+
???Lv 5
+
+
??/??
+
+
+
???Lv 5
+
+
??/??
+
+
EXP: 0/100
+
+
+
A wild creature appeared!
+
+ + + + +
+
+
+
+
+
+
LEVEL UP!
+
+ +
+

+
+ +
+
+
+ +
+

BLACKROAD CREATURES

+

Gotta Route 'Em All

+

WASD / Arrows - Move

+

SPACE - Interact

+

TAB - Creature Index

+

I - Open Bag

+

Collect and battle creatures!

+ +
+
+ + + + diff --git a/blackroad-pixel/games/stardew/index.html b/blackroad-pixel/games/stardew/index.html new file mode 100644 index 0000000..648e891 --- /dev/null +++ b/blackroad-pixel/games/stardew/index.html @@ -0,0 +1,1511 @@ + + + + + +BlackRoad Harvest - Pixel Farm + + + +
+ +
+
+
SEASON:SPRING
+
DAY:1
+
WEATHER:SUNNY
+
TIME:6:00 AM
+
ENERGY:
+
$500
+
+
+
+
+
+
+
+
+
+
SPACE to close / Gift selected crop
+
+
+

BLACKROAD SEED SHOP

+
+ +
+
+

FARMER SAGE'S ANIMALS

+
+ +
+
+

FISHING!

+
+
+
+
+ +
Press SPACE to catch!
+
+
+
+

BLACKROAD HARVEST

+

A Pixel Farming World

+

WASD / Arrows - Move

+

SPACE - Use Tool / Interact / Talk to NPCs

+

1-0 - Select Item (10 slots)

+

E - Open Shop (near store) / NPC shops

+

F - Fish (equip rod near water)

+ +
+
+ + + + diff --git a/blackroad-pixel/games/webkinz/index.html b/blackroad-pixel/games/webkinz/index.html new file mode 100644 index 0000000..7cfa60a --- /dev/null +++ b/blackroad-pixel/games/webkinz/index.html @@ -0,0 +1,1445 @@ + + + + + +BlackRoad Pets - Virtual World + + + +
+ +
+ +
HP
+
FD
+
EN
+
CL
+
XP
Lv1
+ 1000 KC + +
+
+ + + + + + +
+
+ + + + + + + + +
+
+
+
ACHIEVEMENT UNLOCKED!
+ +
+

BLACKROAD PET SHOP

+
+ + + + + +
+
+ +
+ +
+

CHOOSE A MINIGAME

+
+
+ 🍔 + Catch Treats + Catch falling treats with combos & power-ups! +
+
+ 🃏 + Memory Match + Match pairs on a 4x4 grid. Fewer moves = more coins! +
+
+ 🎵 + Rhythm Tap + Tap A/S/D as notes hit the line. Build combos! +
+
+ +
+ +
+

CATCH THE TREATS!

+

Use LEFT/RIGHT arrows to catch falling treats

+ +
Score: 0
+ +
+ +
+

ACHIEVEMENTS

+
+ +
+ +
+

CHOOSE YOUR PET

+

Pick your first BlackRoad companion!

+
+
🐱Neon Cat
+
🐶Cyber Pup
+
🐰Pixel Bunny
+
🦉Code Owl
+
🐲Data Dragon
+
🦊Glitch Fox
+
+
+ + +
+
+
+ + + + diff --git a/blackroad-pixel/index.html b/blackroad-pixel/index.html index 80a59f2..c6362d8 100644 --- a/blackroad-pixel/index.html +++ b/blackroad-pixel/index.html @@ -25,6 +25,7 @@ Terminal Tools Agents + Games