chore: pre-migration snapshot

Layer0, MCP servers, Terraform consolidation

CONTROL_PLANE_README.md

@@ -0,0 +1,151 @@
+# Cloudflare Control Plane
+
+A programmable, verifiable, policy-driven Cloudflare operating system with MCP as the primary interface layer.
+
+## 🏛️ Architecture Overview
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Intent Layer  │◄──►│   State Layer   │◄──►│  Verify Layer   │
+│  (MCP Servers)  │    │   (Terraform)   │    │ (Invariants)    │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  GitOps Layer   │◄──►│  Cloudflare API │◄──►│ Security Layer  │
+│  (Automation)   │    │   (Live State)  │    │   (Layer0)     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+## 🎯 Core Components
+
+### MCP Interface Layer (Intent)
+- **`cloudflare.mcp.cloudflare_safe`**: State mutation operations
+- **`cloudflare.mcp.waf_intelligence`**: Analysis & rule synthesis
+- **`cloudflare.mcp.oracle_answer`**: Security decision support
+
+### Terraform State Layer (Desired State)
+- **DNS Management**: Automated DNS, SPF/DMARC, tunnel routing
+- **WAF Security**: Custom rules + managed rulesets
+- **Tunnel Infrastructure**: Multi-service ingress routing
+- **Bot Management**: Automated detection & mitigation
+
+### GitOps Automation Layer (Change Propagation)
+- **WAF Rule Proposer**: Threat-intel driven rule generation
+- **Invariant Checker**: Real-time state validation
+- **Drift Guardian**: Automated remediation
+- **CI/CD Integration**: GitHub Actions + GitLab CI
+
+### Security Framework Layer (Verification)
+- **Layer0**: Pre-execution security classification
+- **Shadow Classifier**: Threat assessment
+- **Preboot Logger**: Security event tracking
+- **Invariant Validation**: Continuous compliance checking
+
+## 🔄 Operational Flows
+
+### Threat Intelligence → WAF Enforcement
+```
+Threat Intel → WAF Proposal → MR Review → Terraform Apply → Invariant Check → Remediation
+```
+
+### DNS/Tunnel Management
+```
+Service Definition → Tunnel Config → DNS Routing → Health Monitoring → Rotation
+```
+
+### Security Classification
+```
+Query → Layer0 Classification → Routing Decision → Execution/Block → Logging
+```
+
+## 🛡️ Security Posture
+
+### Risk Mitigations
+- **Token Scoping**: Least-privilege API tokens
+- **Rate Limiting**: API call throttling
+- **Audit Trail**: Comprehensive logging
+- **Invariant Checks**: Real-time compliance validation
+
+### Compliance Frameworks
+- PCI-DSS 6.6
+- OWASP-ASVS 13
+- Zero-trust architecture
+
+## 🚀 MCP Server Capabilities
+
+### Cloudflare Safe MCP
+```bash
+# Tools available
+- dns_record_manage
+- waf_rule_configure  
+- tunnel_health_check
+- zone_analytics_query
+```
+
+### WAF Intelligence MCP
+```bash
+# Tools available
+- waf_config_analyze
+- threat_intel_integrate
+- compliance_map_generate
+- rule_gap_identify
+```
+
+### Oracle Answer MCP
+```bash
+# Tools available
+- security_classify
+- routing_decide
+- threat_assess
+- decision_support
+```
+
+## 📊 Monitoring & Observability
+
+### Key Metrics
+- DNS resolution latency
+- WAF rule effectiveness
+- Tunnel health status
+- API rate limit utilization
+- Invariant compliance rate
+
+### Alerting Triggers
+- Invariant violations
+- Tunnel connectivity issues
+- WAF rule deployment failures
+- Security classification anomalies
+
+## 🔧 Development & Extension
+
+### Adding New MCP Servers
+1. Follow wrapper pattern in `/.secret/mcp/template.sh`
+2. Add health checks and PYTHONPATH injection
+3. Register in OpenCode configuration
+4. Add to smoke test (`/test_mcp_servers.sh`)
+
+### Extending Terraform Modules
+- Maintain compatibility with existing state
+- Add corresponding invariant checks
+- Update GitOps automation
+
+### Security Framework Integration
+- Extend Layer0 classification rules
+- Add new threat intelligence sources
+- Enhance compliance mappings
+
+## 🎯 Production Readiness
+
+### ✅ Completed
+- Deterministic MCP interfaces
+- GitOps automation pipeline
+- Real-time invariant checking
+- Security classification framework
+
+### 🔄 Operational Excellence
+- Automated remediation
+- Comprehensive monitoring
+- Audit trail preservation
+- Compliance validation
+
+This control plane represents a **foundational infrastructure layer** that can support higher-level automation, agent systems, and compliance proofs without architectural changes.