Verify end-to-end on kind: fix Squid FD-table OOM, make the quickstart in-cluster

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

README.md

@@ -31,17 +31,26 @@ Details, diagrams, and recorded design decisions: [docs/architecture.md](docs/ar
 
 ## Quickstart on kind (~5 minutes)
 
-Requires: kind, kubectl, Go 1.26, jq (optional). The kubernetes-pod
-provider needs no cloud account — proxies are real `ubuntu/squid` pods in
-the kind cluster itself.
+Requires: kind, kubectl, docker, Go 1.26, jq (optional). The
+kubernetes-pod provider needs no cloud account — proxies are real
+`ubuntu/squid` pods in the kind cluster itself.
+
+The operator runs **in-cluster** for this quickstart. (Running it on your
+laptop with `make run-dev` provisions pods fine, but the health probe then
+originates on your machine, which cannot reach kind's pod IPs — the proxy
+would sit at `Unhealthy` forever. In-cluster, probes run where the pod
+network is routable.)
 
 ```sh
 kind create cluster --name proxy-operator-demo
-make install                                  # install the CRD
-make run-dev                                  # run the operator locally (foreground)
+make install                                          # install the CRD
+make docker-build IMG=egress-proxies-operator:dev
+kind load docker-image egress-proxies-operator:dev --name proxy-operator-demo
+make deploy IMG=egress-proxies-operator:dev
+kubectl -n egress-proxies-operator-system rollout status deploy/egress-proxies-operator-controller-manager
 ```
 
-In a second terminal:
+Create a proxy and watch it come up:
 
 ```sh
 kubectl apply -f config/samples/proxy_kubernetes.yaml
@@ -50,7 +59,12 @@ kubectl get px -w
 # proxy-kubernetes-sample   Managed   kubernetes   Ready   10.244.x.x   True
 ```
 
-Once it's `Ready`, use the discovery API:
+Once it's `Ready`, port-forward the discovery API and use it:
+
+```sh
+kubectl -n egress-proxies-operator-system port-forward \
+  svc/egress-proxies-operator-controller-manager-discovery-service 8090:8090 &
+```
 
 ```sh
 # List healthy proxies
@@ -156,11 +170,17 @@ Makefile's derived version to 1.36.3, which has none).
 ## Development
 
 ```sh
-make test        # unit + envtest suites (sets up envtest binaries itself)
+make test        # unit + envtest suites, with -race (sets up envtest binaries itself)
 go test -short ./...   # skip the envtest suite
 make run-dev     # run against the current kubeconfig context
 ```
 
+`make run-dev` is for iterating on the operator itself: provisioning,
+replacement, the discovery API, and External proxies all work from your
+laptop. Health checks against in-cluster pods do **not** (see the
+quickstart note) — use the in-cluster deploy to see a kubernetes-provider
+proxy go `Ready`.
+
 Project layout, reconcile-loop diagrams, and the decision log are in
 [docs/architecture.md](docs/architecture.md); the build history is in
 [docs/plans-executions/](docs/plans-executions/).