diff --git a/README.md b/README.md
index 93a2290..960a029 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,15 @@
 # Traefik error pages
 
-A small, portable Kubernetes deployment that replaces Traefik-generated HTTP
-5xx response bodies with a Cloudflare-style diagnostic page while preserving
-the original status code. API clients still receive `500`, `502`, `503`, or
-`504`; only the response body and diagnostic headers are replaced.
+A small, portable Kubernetes deployment that serves a Cloudflare-style
+diagnostic page for reverse-proxy failures while preserving the original HTTP
+status code.
+
+Traefik's native Errors middleware matches status codes only; it cannot tell a
+Traefik transport failure from an application's intentional JSON or HTML 5xx.
+The brunner.ninja Traefik release therefore uses the local
+`upstreamErrorPages` filter in `../traefik/upstream-error-pages-plugin.yaml`.
+It replaces only Traefik's exact plain-text upstream failure responses and
+passes application responses through unchanged.
 
 The page reports the browser, reverse proxy, optional ForwardAuth provider, and
 upstream states. Routes without ForwardAuth omit the authentication stage
@@ -60,25 +66,27 @@ also pass the resulting Deployment name through `DEPLOYMENT_NAME`.
 
 ## Connect it to Traefik
 
-Installing the chart creates the error backend and middleware but does not edit
-an independently managed Traefik release. Attach the middleware globally to
-the HTTPS entrypoint in Traefik's Helm values:
+Installing the chart creates the error backend and a native Errors middleware
+but does not edit an independently managed Traefik release.
+
+For brunner.ninja, install the upstream-only local plugin with the Traefik
+release and attach that filter globally:
 
 ```yaml
 ports:
   websecure:
     http:
       middlewares:
-        - default-upstream-errors@kubernetescrd
+        - default-upstream-error-pages@kubernetescrd
 ```
 
-The reference format is `<namespace>-<middleware>@kubernetescrd`. The included
-`examples/traefik-values.yaml` contains this configuration. Restart or upgrade
-Traefik after changing its static entrypoint configuration.
+See `../traefik/traefik-values.yaml` for the plugin mount and static plugin
+registration. Restart or upgrade Traefik after changing its static entrypoint
+configuration.
 
-To use the page only on selected routes, omit the global entrypoint middleware
-and use the annotation shown in `examples/ingress.yaml`, or add this middleware
-to an IngressRoute:
+On clusters where replacing every application 5xx is acceptable, the native
+middleware can still be attached to selected routes using the annotation shown
+in `examples/ingress.yaml`, or added to an IngressRoute:
 
 ```yaml
 middlewares:
@@ -86,8 +94,10 @@ middlewares:
     namespace: default
 ```
 
-Traefik's Errors middleware preserves the original status. It asks this service
-for `/{status}.html`, replaces the body, and returns the original 5xx code.
+The native middleware preserves the original status, asks this service for
+`/{status}.html`, replaces the body, and returns the original 5xx code. Do not
+attach it globally when routes serve APIs: it will replace their JSON 5xx
+bodies too.
 
 ## Optional ForwardAuth diagnostics