Update README with build/connect instructions, add use cases to design doc

- README: add from-source build + Claude Code/Desktop connection steps
- Design doc: add platform admin (DNSPolicy/Route53) and developer
  (RateLimitPolicy) use cases with diagnostic flows
- Remove obsolete files: process-docs.go, update-docs.sh, UPDATE_DOCS.md,
  run_with_logging.sh, demo gif/mp4

Author: maleck13

README.md

@@ -4,9 +4,15 @@ A Model Context Protocol (MCP) server for debugging Kuadrant installations. Prov
 
 ## Quick Start
 
+### From source
+
 ```bash
-# Add the MCP server (available in all projects)
-claude mcp add -s user kuadrant docker -- run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest
+# Build
+git clone https://github.com/kuadrant/kuadrant-mcp-server && cd kuadrant-mcp-server
+go build -o kuadrant-mcp-server
+
+# Add to Claude Code (available in all projects)
+claude mcp add -s user kuadrant -- /path/to/kuadrant-mcp-server
 
 # Verify
 claude mcp list
@@ -15,37 +21,46 @@ claude mcp list
 claude
 ```
 
-## Installation
+### Docker
 
 ```bash
-# Docker (recommended)
-docker pull ghcr.io/kuadrant/kuadrant-mcp-server:latest
-
-# Go
-go install github.com/kuadrant/kuadrant-mcp-server@latest
+# Add to Claude Code
+claude mcp add -s user kuadrant docker -- run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest
 
-# From source
-git clone https://github.com/kuadrant/kuadrant-mcp-server && cd kuadrant-mcp-server
-go build -o kuadrant-mcp-server
+# Verify
+claude mcp list
 ```
 
 ## Usage
 
+The server supports three transport modes:
+
 ```bash
-# stdio (default)
+# stdio (default) — used by Claude Code and Claude Desktop
 ./kuadrant-mcp-server
 
-# SSE transport
+# SSE transport — for web-based MCP clients
 ./kuadrant-mcp-server -transport sse -addr :8080
 
-# HTTP transport
+# HTTP transport — StreamableHTTP for modern web clients
 ./kuadrant-mcp-server -transport http -addr :8080
+```
+
+### Claude Desktop Configuration
 
-# Docker
-docker run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest
+Add to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kuadrant": {
+      "command": "/path/to/kuadrant-mcp-server"
+    }
+  }
+}
 ```
 
-### MCP Client Configuration
+Or using Docker:
 
 ```json
 {

docs/designs/2026-03-20-debugging-mcp-design.md

@@ -136,6 +136,61 @@ Arguments with no default instruct the LLM to ask the user if not provided.
 - **Integration tests**: MCP protocol-level tests — initialize server, call `prompts/list`, invoke a prompt, call `resources/list`, read a resource. Verify JSON-RPC responses.
 - **Manual testing**: End-to-end with Claude Code + Kubernetes MCP server against a live cluster.
 
+## Use Cases
+
+### Platform Admin: DNS records not being created for gateways
+
+**Persona:** Platform engineer responsible for Kuadrant installation and infrastructure.
+
+**Scenario:** A DNSPolicy targeting a Gateway is created but no DNS records appear in Route53. The policy may show Accepted but records are missing from the hosted zone.
+
+**Prompt:** `debug-dnspolicy` with `policy-name` argument.
+
+**Diagnostic flow:**
+1. Check DNSPolicy .status.conditions (Accepted/Enforced)
+2. Verify target Gateway exists and listeners have explicit hostnames
+3. Check DNS provider credentials Secret exists and has correct Route53 permissions (route53:ChangeResourceRecordSets, route53:ListHostedZones)
+4. List DNSRecord CRs — these are the intermediate resources DNSPolicy creates. Check their .status for provider-specific errors
+5. Check kuadrant-operator logs for DNS reconciliation errors
+6. Verify Route53 hosted zone covers the listener hostnames
+
+**Common fixes:**
+- Credentials Secret missing or in wrong namespace
+- IAM permissions insufficient for Route53 operations
+- Gateway listeners missing explicit hostnames
+- Hosted zone doesn't cover the listener hostnames
+- targetRef.group missing from the policy
+
+**Resources used:** `kuadrant://debug/dnspolicy`, `kuadrant://debug/status-conditions`
+
+### Developer: RateLimitPolicy not enforcing rate limits
+
+**Persona:** Application developer creating policies for their services.
+
+**Scenario:** A RateLimitPolicy is created targeting a Gateway or HTTPRoute, but traffic is not being rate limited. Requests that should return 429 are passing through.
+
+**Prompt:** `debug-ratelimitpolicy` with `policy-name` argument.
+
+**Diagnostic flow:**
+1. Check RateLimitPolicy .status.conditions (Accepted/Enforced)
+2. Verify targetRef points to an existing Gateway or HTTPRoute with correct kind, name, and group
+3. Inspect rate limit configuration — rates must have limit (int) and window (duration string)
+4. Check for policy conflicts — multiple policies targeting the same resource, defaults vs overrides hierarchy
+5. Verify Limitador pods are running and processing the policy (check logs)
+6. Test by sending requests exceeding the limit within the window
+7. Check Istio/Envoy — verify EnvoyFilter resources exist for the policy
+
+**Common fixes:**
+- targetRef.group missing (should be "gateway.networking.k8s.io")
+- targetRef points to wrong or non-existent resource
+- Policy Accepted but not Enforced — Limitador not running
+- Targeting Gateway when per-route limiting is needed (should target HTTPRoute)
+- "when" conditions too restrictive — limits never triggered
+- Gateway-level overrides taking precedence over route-level policy
+- Limitador crashlooping due to config errors or Redis connectivity
+
+**Resources used:** `kuadrant://debug/ratelimitpolicy`, `kuadrant://debug/status-conditions`, `kuadrant://debug/policy-conflicts`
+
 ## Open Questions
 
 - None currently