diff --git a/README.md b/README.md
index 0e99a22..64abbef 100644
--- a/README.md
+++ b/README.md
@@ -4,57 +4,81 @@ A real, multi-host homelab run as a production-grade platform — not a pile of
This repo is a sanitized showcase of the systems behind that platform — the actual engineering decisions and tradeoffs, not just a list of installed apps. Every real IP, hostname, and internal domain has been stripped or genericized throughout.
+
+
+11 fleet hosts |
+55 compose stacks |
+16 documented systems |
+4 trust boundaries |
+13 automated maintenance flows |
+
+
+
## Architecture at a glance
```mermaid
-flowchart TD
- Internet(["Internet"])
- Edge["Edge Firewall
NAT · public reverse proxy · NTP · DHCP"]
- LAN["LAN"]
- DNS["Internal DNS
two zones: browser-facing / service-to-service"]
- Vault["Vault
PKI + secret store"]
+flowchart LR
+ Internet(["Internet"]) --> Edge["Edge Firewall"]
+ Edge --> LAN["LAN"]
- Apps["App Host (LXC)
~40 Docker Compose stacks"]
- InternalProxy["Internal reverse-proxy zone
app-to-app HTTPS"]
- SSO["SSO / forward-auth"]
-
- FileServer["File Server
NFS · SMB"]
- Automation["Automation VM
Git hosting · orchestration"]
- EdgeProxy["User-facing reverse proxy
mTLS enforced"]
- Monitoring["Monitoring
metrics · logs"]
- SecMonitoring["Security Monitoring
SOC stack"]
-
- Internet --> Edge --> LAN
- LAN --> DNS
- LAN --> Vault
+ LAN --> DNS["Internal DNS
two zones"]
+ LAN --> Vault["Vault
PKI + secrets"]
DNS --> Vault
- Vault --> Apps
- LAN --> FileServer
+ Vault --> Apps["App Host
41 stacks"]
+ Vault --> Automation["Automation VM
Git + orchestration"]
+ LAN --> FileServer["File Server"]
DNS --> FileServer
- Vault --> Automation
LAN --> Automation
- Apps --> InternalProxy
- Apps --> SSO
+ Apps --> InternalProxy["Internal Proxy Zone"]
+ Apps --> SSO["SSO"]
- Vault --> EdgeProxy
+ Vault --> EdgeProxy["User-Facing Proxy
mTLS"]
DNS --> EdgeProxy
- Apps -. proxied by .-> EdgeProxy
- SSO -. auth gate via .-> EdgeProxy
+ Apps -.proxied.-> EdgeProxy
+ SSO -.auth.-> EdgeProxy
- Apps -. reports to .-> Monitoring
- Automation -. reports to .-> Monitoring
- FileServer -. reports to .-> Monitoring
- EdgeProxy -. reports to .-> Monitoring
+ Apps -.-> Monitoring["Monitoring"]
+ Automation -.-> Monitoring
+ FileServer -.-> Monitoring
+ EdgeProxy -.-> Monitoring
- Apps -. reports to .-> SecMonitoring
- Automation -. reports to .-> SecMonitoring
- FileServer -. reports to .-> SecMonitoring
- EdgeProxy -. reports to .-> SecMonitoring
+ Apps -.-> SecMon["Security Monitoring"]
+ Automation -.-> SecMon
+ FileServer -.-> SecMon
+ EdgeProxy -.-> SecMon
+
+ classDef edge fill:#f8cecc,stroke:#b85450,color:#333
+ classDef core fill:#dae8fc,stroke:#6c8ebf,color:#333
+ classDef obs fill:#fff2cc,stroke:#d6b656,color:#333
+ class Internet,Edge edge
+ class LAN,DNS,Vault,Apps,Automation,FileServer,InternalProxy,SSO,EdgeProxy core
+ class Monitoring,SecMon obs
```
-Full traffic-law breakdown (ingress, east-west, secrets, DNS, observability, notifications, CI/CD, and management planes, each with its own failure behavior): [docs/architecture-overview.md](docs/architecture-overview.md).
+Solid arrows are real dependencies; dotted arrows are asynchronous telemetry reporting, not a blocking dependency. Full breakdown of all 8 traffic laws (ingress, east-west, secrets, DNS, observability, notifications, CI/CD, management) with the actual trust-boundary reasoning: [docs/architecture-overview.md](docs/architecture-overview.md).
+
+## Every system, at a glance
+
+| System | The core decision | Doc |
+|---|---|---|
+| 🔐 Secrets & PKI | One Vault cluster as CA + secret store, zero plaintext secrets in git | [→](docs/secrets-and-pki.md) |
+| 🔑 Secret Distribution | Four distinct flows, each with its own failure contract | [→](docs/secret-distribution.md) |
+| 🪪 SSO & Identity | Dual-zone SSO registration, header-based fallback for a real LDAP limitation | [→](docs/sso-and-identity.md) |
+| 🧱 Firewall & Network | Zero blanket-allow rules — every flow explicit, everything else dropped | [→](docs/firewall-and-network.md) |
+| 🌐 DNS | Two zones decide which trust boundary a request enters | [→](docs/dns-naming.md) |
+| 📈 Observability | Push-based metrics, chosen specifically to fit the firewall model | [→](docs/observability.md) |
+| 🛡️ Security Monitoring | Curated alert runbook + justified compliance exceptions | [→](docs/security-monitoring.md) |
+| 🔁 Orchestration | 13 flows, check → pause → human approval → apply | [→](docs/orchestration.md) |
+| 🔔 Notifications | Two fan-in branches, one shared formatter, zero runtime coupling | [→](docs/notifications.md) |
+| 📦 Registry & Build | Self-hosted registry, digest-checked before any rebuild | [→](docs/registry-and-build.md) |
+| 🖥️ Dashy SOC Board | 14 data sources aggregated into one glanceable board | [→](docs/dashy-soc-board.md) |
+| ⏱️ Cron Scheduler | Fleet-wide job inventory, weighted load heatmap | [→](docs/cron-scheduler.md) |
+| 📝 Content Pipeline | In-progress, shown honestly rather than hidden | [→](docs/content-pipeline.md) |
+| 🏗️ Infrastructure as Code | Packer → Terraform → Ansible, one tag threading all three | [→](docs/iac-pipeline.md) |
+| 🧯 Disaster Recovery | 3 independent recovery layers, one real documented gap | [→](docs/disaster-recovery.md) |
+| 📐 Architecture Overview | 4 trust boundaries, 3 routing authorities, calibrated not maxed | [→](docs/architecture-overview.md) |
## Systems