From ab8fae388c629b3edd53504e43cc1fedce018db0 Mon Sep 17 00:00:00 2001
From: Joey Smith <jsmith@webinertia.net>
Date: Thu, 24 Sep 2026 20:12:11 -0500
Subject: [PATCH] docs: correct the pipeline wiring instructions

The README claimed the middleware self-registers via ConfigProvider and
that no pipeline edit was needed. It does not: ConfigProvider registers
the middleware factory and the navigation view helper and nothing else,
so a consumer following that advice gets middleware that never runs.

Replaced with the requirement itself, plus why Mezzio's
middleware_pipeline is deliberately unused: a priority integer cannot
express the ordering this depends on. Refs docs/architecture.md,
Decision 7.
---
 README.md | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4758d66..fd9a23f 100644
--- a/README.md
+++ b/README.md
@@ -48,8 +48,24 @@ Add to `config/config.php`:
 Webware\Navigation\ConfigProvider::class,
 ```
 
-The middleware is self-registering via `ConfigProvider`. No manual pipeline edit
-is required beyond the entry in `config/config.php`.
+That registers the middleware factory and the `navigation` view helper. The
+middleware itself is **not** piped for you: add it to `config/pipeline.php`
+after `RouteMiddleware` and before `DispatchMiddleware`, so that `RouteResult`
+is on the request by the time it runs:
+
+```php
+$app->pipe(RouteMiddleware::class);
+// ...
+$app->pipe(UrlHelperMiddleware::class);
+$app->pipe(NavigationMiddleware::class);
+$app->pipe(DispatchMiddleware::class);
+```
+
+The package deliberately does not self-register through Mezzio's
+`middleware_pipeline` config. That mechanism orders middleware by an integer
+priority, and this middleware's correctness depends on running after
+`RouteMiddleware` and before `DispatchMiddleware`, an ordering such a priority
+cannot express safely. See [Architecture](docs/architecture.md), Decision 7.
 
 ## Namespace