chore: pre-migration snapshot

Layer0, MCP servers, Terraform consolidation

REGISTRY_ENHANCEMENT_SUMMARY.md

@@ -0,0 +1,121 @@
+# Cloudflare Control Plane Registry Enhancement Summary
+
+## ✅ Enhanced Capability Registry (v1.0.1)
+
+**Key improvements implemented:**
+
+### 1. **Exact MCP Tool Names & Entrypoints**
+- **Cloudflare Safe**: `cf_snapshot`, `cf_refresh`, `cf_config_diff`, etc.
+- **WAF Intelligence**: `waf_capabilities`, `waf_analyze`, `waf_assess`, etc.  
+- **Oracle Answer**: `oracle_answer`
+- **Entrypoints**: Exact Python module paths for execution
+
+### 2. **Operational Metadata**
+- **Auth/Env**: Required environment variables per server
+- **Side Effects**: Clear indication of read-only vs. mutating operations
+- **Outputs**: Specific output formats (JSON, Terraform HCL, GitOps MRs)
+
+### 3. **Drift Prevention**
+- **Tools section**: Exact MCP tool names prevent registry/source mismatch
+- **Entrypoint specification**: Prevents confusion between modules and runnable servers
+- **File references**: Uses actual file names (e.g., `invariant_checker_py.py`)
+
+### 4. **Machine-Checkable Contract**
+The registry now serves as a **verifiable contract** between:
+- **Documentation**: What capabilities are claimed
+- **Implementation**: What tools are actually exposed
+- **Operations**: What side effects and auth are required
+
+## 🎯 Registry Structure
+
+### MCP Server Template
+```yaml
+server_name:
+  module: "exact.python.module.path"
+  entrypoint: "runnable.server.path"  
+  purpose: "clear operational purpose"
+  tools: ["exact_tool_name (operation_type)"]
+  auth_env: ["REQUIRED_VARS"]
+  side_effects: "read-only | propose | mutate"
+  outputs: ["json", "terraform_hcl", "gitops_mr"]
+```
+
+### GitOps Tool Template
+```yaml
+tool_name:
+  file: "exact/file/path.py"
+  purpose: "specific operational function"
+  side_effects: "creates MRs | applies changes | generates reports"
+  outputs: ["terraform_apply", "gitops_mr", "anomaly_report"]
+```
+
+## 🔒 Audit-Grade Features
+
+### Compliance Validation
+- **Tool enumeration**: Every MCP tool is explicitly listed
+- **Access control**: Auth requirements clearly documented
+- **Change tracking**: Versioned registry with generation timestamps
+
+### Operational Transparency
+- **Side effects**: Clear about mutating vs. read-only operations
+- **Output formats**: Specific about what each component produces
+- **Dependencies**: Environmental requirements explicitly stated
+
+### Drift Detection
+- **File references**: Uses actual file names to prevent rename drift
+- **Module paths**: Exact Python module paths prevent import confusion
+- **Tool names**: Exact MCP tool names prevent capability mismatch
+
+## 🚀 Usage Examples
+
+### For Auditors
+```bash
+# Verify MCP server capabilities match documentation
+cat capability_registry_v2.json | jq '.mcp_servers.cloudflare_safe.tools'
+
+# Check operational requirements  
+cat capability_registry_v2.json | jq '.mcp_servers.cloudflare_safe.auth_env'
+```
+
+### For Developers
+```bash
+# Validate new MCP server against registry template
+python3 generate_capability_registry_v2.py
+
+# Check for capability drift
+diff capability_registry_v2.json capability_registry.json
+```
+
+### For Operations
+```bash
+# Verify side effects before deployment
+cat capability_registry_v2.json | jq '.mcp_servers.cloudflare_safe.side_effects'
+
+# Check output formats for integration
+cat capability_registry_v2.json | jq '.gitops_tools.waf_rule_proposer.outputs'
+```
+
+## 📊 Registry Files Generated
+
+1. **`capability_registry_v2.json`** - Machine-readable contract
+2. **`CAPABILITY_REGISTRY_V2.md`** - Human-readable documentation
+3. **`generate_capability_registry_v2.py`** - Regeneration script
+
+## 🎯 Next Steps
+
+### Continuous Validation
+- Add CI check to validate MCP tool names against registry
+- Automated drift detection between registry and source code
+- Periodic registry regeneration as capabilities evolve
+
+### Extended Metadata
+- Add performance characteristics (timeouts, rate limits)
+- Include error handling patterns
+- Add recovery procedures for failed operations
+
+### Integration Testing
+- Use registry to generate comprehensive test suites
+- Validate auth/env requirements in test environment
+- Verify side effects and outputs match expectations
+
+This enhanced registry transforms the Cloudflare control plane from **documented infrastructure** to **verifiable, auditable, and drift-resistant infrastructure**.