From da223e3456f2a72dc82c814bdca9f110ae869f9b Mon Sep 17 00:00:00 2001
From: rockachopa <alexpaynex@gmail.com>
Date: Wed, 29 Jul 2026 21:22:09 +0000
Subject: [PATCH] Add README.md

---
 README.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 119 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5795901..fc59896 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,120 @@
-# sovereign-stack
+# Sovereign AI Stack
 
-Sovereign AI Stack — product portfolio and sellable assets: local-first multi-agent platform, L402 payments, deployment kits, voice personas.
\ No newline at end of file
+Local-first multi-agent system. Your data, your models, your rules.
+
+No cloud API dependencies. No subscription. No one else’s uptime requirement.
+
+---
+
+## What this is
+
+Sovereign AI Stack is a production-grade agent runtime you own end to end.
+
+It runs on your hardware, talks to local LLMs through Ollama, discovers tools dynamically via MCP, coordinates multiple agents through an auction-based swarm, and even accepts Bitcoin micropayments for API access via L402.
+
+You ship it behind your firewall, your VPN, or your home router. Your prompts, your memory, your data never leave your box.
+
+---
+
+## Stack
+
+- **AI runtime:** MCP tool discovery + Agno-style coordinator/sub-agent swarm + cascade LLM routing
+- **Interface:** FastAPI backend + HTMX dashboard + WebSocket live feed
+- **Storage:** SQLite with backup/restore runbooks
+- **Auth / revenue:** L402 Lightning payment proxy (optional)
+- **Infra:** Docker Compose deploy, GitHub Actions CI, 228+ tests, 60% coverage floor, watchdog monitoring
+- **Voice:** Optional persona runtime with TTS/STT and RTMP ingest
+
+---
+
+## Who this is for
+
+- Privacy-first developers who want AI without sending prompts to OpenAI/Anthropic
+- Bitcoin/sovereign operators running home labs and full nodes
+- Engineering leads who need an internal agent runtime they can audit and extend
+- Hackers/indie devs who want a local agent stack they can modify, not rent
+
+---
+
+## What you get
+
+### Self-hosted
+- Full Docker Compose deploy
+- README + architecture diagram + threat model
+- 30-minute setup on x86_64 or Apple Silicon
+- Includes: MCP auto-discovery, coordinator swarm, dashboard, WebSocket UI, L402 payment gateway
+
+### Supported
+- Everything in self-hosted
+- 1-hour onboarding call
+- 30-day support window
+- Security patch notifications
+- $199/month or $1,999/year
+
+### Enterprise
+- Multi-node orchestration
+- SSO + team auth
+- Custom MCP tool integration
+- On-prem install or air-gapped bundle
+- $5,000 flat + support retainer
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  Dashboard + WebSocket UI (HTMX)        │
+├─────────────────────────────────────────┤
+│  Coordinator / Swarm Router             │
+│  Auction-based task assignment           │
+├─────────────────────────────────────────┤
+│  MCP Auto-Discovery Layer               │
+│  Dynamic tool registration + execution  │
+├─────────────────────────────────────────┤
+│  Cascade LLM Router                     │
+│  Ollama primary → provider fallback      │
+├─────────────────────────────────────────┤
+│  SQLite Persistence + Backup/Restore    │
+├─────────────────────────────────────────┤
+│  L402 Lightning Payment Proxy           │
+│  Macaroon auth + Bitcoin micropayments   │
+└─────────────────────────────────────────┘
+         ↓ optional persona runtime
+┌─────────────────────────────────────────┐
+│  TTS / STT / RTMP / Avatar              │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Security model
+
+- All inference happens locally. No prompt exfiltration path to third-party APIs in default config.
+- L402 uses HMAC macaroons, not credential databases.
+- All state is SQLite-backed; backup/restore is tested.
+- CI runs 228+ tests with coverage floor enforced by watchdog.
+- No telemetry, no phone-home, no usage tracking by default.
+
+---
+
+## Demo
+
+*Coming soon — 3-minute walkthrough of local-first agent completing a real task without cloud APIs.*
+
+---
+
+## Pricing
+
+- **Self-hosted:** $2,500 one-time setup fee + optional support
+- **Supported:** $199/month
+- **Enterprise:** $5,000 flat + retainer
+
+Payment accepted in USD or Lightning.
+
+---
+
+## Contact
+
+alex@alexanderwhitestone.com
+github.com/Alexspayne