diff --git a/README.md b/README.md
index b715263..10047e9 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,8 @@ It runs as a [Yaegi](https://github.com/traefik/yaegi)-interpreted Go
 module, the same way [`traefikoidc`](https://github.com/lukaszraczylo/traefikoidc)
 does, configured per-middleware in Traefik's dynamic configuration.
 
-> [!WARNING]
-> **Experimental — proof of concept.** Until version 1.0 this project is an
+> **⚠️ WARNING — experimental, proof of concept.**
+> Until version 1.0 this project is an
 > experiment in PoC development stage, not production ready. Configuration
 > keys, endpoints, and behaviour can change between pre-1.0 releases without
 > a deprecation period. Evaluate it, test it, break it — but do not put it
@@ -39,6 +39,9 @@ Catalog — see [Development](#development) for what that needs.
   agents, so those can sit behind the same gateway, the same auth, and the
   same group-based visibility rules as the LLM traffic.
 
+<details>
+<summary><b>Request flow diagram</b> (mermaid — renders on GitHub)</summary>
+
 ```mermaid
 flowchart LR
     Req["incoming request"] --> Route{"route<br/>ServeHTTP: path+method dispatch"}
@@ -74,6 +77,8 @@ flowchart LR
     Registry --> Resp
 ```
 
+</details>
+
 Every route the plugin recognises is handled entirely inside the
 middleware — `next` (the router's configured backing service) is only
 reached when a request matches none of the plugin's routes and