docs: rewrite CLAUDE.md to house conventions, fix flows.md and README

- CLAUDE.md in five sections with Go, testing, plan, changelog, branching
  and tagging rules; known sharp edges moved to Gotchas
- docs/flows.md: metrics are served on :8080, name collisions are rejected
  by the API server, last-cert deletion never cleans up
- README moved to the repo root, deploy command corrected

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,66 @@
+# Gateway Certificate Operator
+
+The `gateway-cert-operator` automates the configuration of Gateway API `Gateway` listeners when using `cert-manager` for TLS certificate management.
+
+## Overview
+
+When you create a `Certificate` resource using `cert-manager`, this operator automatically and dynamically creates an HTTPS `Listener` on your target Gateway. This eliminates the need for manual configuration of the Gateway each time a new certificate is provisioned or its DNS names change.
+
+## Architecture
+
+The operator acts as a bridge between two standard Kubernetes APIS:
+- `cert-manager.io/v1` `Certificate`
+- `gateway.networking.k8s.io/v1` `Gateway`
+
+By watching both resources, the controller ensures that the Gateway always has the correct listeners configured to serve HTTPs traffic for the domains requested in the certificates.
+
+## Prerequisites
+
+- A Kubernetes cluster.
+- [Gateway API](https://gateway-api.sigs.k8s.io/) installed (`v1` APIs).
+- [cert-manager](https://cert-manager.io/) installed (`v1` APIs).
+
+## Usage
+
+To use the operator, simply add the appropriate annotations to your `Certificate` resource.
+
+### Example Certificate
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: my-app-cert
+  namespace: default
+  annotations:
+    # Required: The name of the target Gateway
+    gateway-cert-operator.io/gateway-name: "my-gateway"
+    
+    # Optional: If the Gateway is in a different namespace
+    # gateway-cert-operator.io/gateway-namespace: "gateway-system"
+spec:
+  secretName: my-app-tls
+  dnsNames:
+    - "app.example.com"
+  issuerRef:
+    name: letsencrypt-prod
+    kind: ClusterIssuer
+```
+
+### Lifecycle
+
+1. **Trigger**: The operator detects the `gateway-cert-operator.io/gateway-name` annotation on the `Certificate`.
+2. **Gateway Lookup**: It fetches the designated target Gateway (`my-gateway`).
+3. **Patching**: For each DNS name defined in `spec.dnsNames`, it mathematically appends a new HTTPS `Listener` on port `443` terminating TLS using the secret created by `cert-manager` (`my-app-tls`).
+4. **Safe Coexistence**: To safely coexist with manually defined listeners, the operator uniquely prefixes its configured listeners with `auto-` (e.g., `auto-my-app-cert-app-example-com`). It solely manages listeners with this prefix. 
+
+When a certificate is updated (for instance if a DNS name is changed), the operator removes the older `auto-*` listeners and inserts the new ones while preserving the manually defined resources.
+
+Known limitation: when a certificate is deleted, its listeners are removed only on the next reconcile of another certificate targeting the same Gateway.
+
+## Deployment
+
+To deploy the operator, applying the provided manifest sets up the necessary RBAC permissions and the controller manager:
+
+```bash
+kubectl apply -k deploy/
+```