diff --git a/demo-client/README.adoc b/demo-client/README.adoc
index f172a5fd..720dbd74 100644
--- a/demo-client/README.adoc
+++ b/demo-client/README.adoc
@@ -8,8 +8,9 @@ drives it in a real browser against the running `integration-tests` stack.
 
 The SPA is served *by the gateway itself* as a public asset, so it is same-origin with the reserved
 `/auth` paths and exercises the genuine browser-facing contract. The suite runs the same specs
-against *both* session modes -- `server` on port 10443 and `cookie` on port 10445 -- so "the two
-variants are browser-observably identical" is an executable assertion rather than a claim.
+against *both* session modes, which turns "the two variants are browser-observably identical" into an
+executable assertion rather than a claim -- see
+link:doc/playwright-suite.adoc#_why_the_demo_exists[Why the Demo Exists].
 
 This module ships no Java and produces no artifact. Nothing here reaches the production image or the
 native executable.
@@ -25,84 +26,63 @@ toolchain into `target/` and installs the Chromium build Playwright drives.
 == Running It
 
 One command does everything -- toolchain install, lint, browser install, three-container bring-up,
-both Playwright projects, teardown:
+both Playwright projects, and teardown on a successful run:
 
 [source,bash]
 ----
-python3 .plan/execute-script.py plan-marshall:build-maven:maven \
-  run --command-args "verify -Pe2e-demo -pl demo-client"
+./mvnw verify -Pe2e-demo -pl demo-client
 ----
 
-When iterating on specs, hold the stack up and re-run only the tests:
+A *failing* suite deliberately leaves the containers up: the npm goal aborts the build before Maven
+reaches its teardown phase, so the stack you need for diagnosis is still there. Stop it with
+`demo-client/scripts/stop-dev-environment.sh`, or with a `clean` build under the same profile
+(`./mvnw clean -Pe2e-demo -pl demo-client`) -- the `pre-clean` teardown lives inside `e2e-demo`, so a
+plain `clean` does not run it. See
+link:doc/playwright-suite.adoc#_running_the_suite_locally[Running the Suite Locally].
+
+When iterating on specs, hold the stack up and re-run only the tests. `playwright.config.js` takes
+its three addresses from the environment and fails loudly when any is unset; the `e2e-demo` profile
+supplies them from `demo-client/pom.xml`, so a standalone run has to export them itself:
 
 [source,bash]
 ----
 demo-client/scripts/start-dev-environment.sh
+
+# Mirrors the demo.baseUrl.server, demo.baseUrl.cookie and demo.keycloak.url properties in
+# demo-client/pom.xml, which remain the single source of these addresses.
+export PLAYWRIGHT_BASE_URL_SERVER=https://localhost:10443
+export PLAYWRIGHT_BASE_URL_COOKIE=https://localhost:10445
+export KEYCLOAK_HOST_URL=https://localhost:1443
+
 cd demo-client && npm run test
 demo-client/scripts/stop-dev-environment.sh
 ----
 
-`npm run test`, never `npx`: `npm run` resolves the binary from `node_modules/.bin` only, so a
-missing binary is a hard failure rather than a silent registry download. The build makes the same
-choice, for the same reason.
-
-Without `-Pe2e-demo` this module is a no-op: a default reactor build downloads no Node, runs no npm
-command, starts no container and produces no artifact.
+`npm run test`, never `npx` -- and no Maven npm execution runs outside `-Pe2e-demo`: a default
+reactor build downloads no Node, runs no npm command, starts no container and produces no artifact.
+The direct `npm run test` above is the one npm invocation outside the profile, and it is a deliberate
+developer opt-in rather than part of any build. Both are load-bearing choices rather than style, and
+the reasoning is in link:doc/playwright-suite.adoc#_the_opt_in_mechanism[The Opt-In Mechanism].
 
 Once the stack is up, the application is at `https://localhost:10443/assets/demo/index.html`
 (server-session mode) and `https://localhost:10445/assets/demo/index.html` (cookie mode). Sign in as
-`integration-user` / `integration-password`. Note the explicit filename -- the gateway serves no
-directory index, so `/assets/demo/` returns `404`.
-
-== Where the Output Lands
-
-Everything generated sits under `target/` and is git-ignored:
-
-[cols="1,2"]
-|===
-| Path | Contents
-
-| `target/test-results/`
-| Playwright JSON and JUnit results. There is no HTML reporter, so no report server is spawned.
-
-| `target/screenshots/{project}/`
-| The documentation screenshots -- `anonymous`, `authenticated-default-view`,
-  `full-allowlisted-view`, `claim-denied`, `logged-out` -- one parallel set per session mode.
-
-| `target/node/`, `target/node_modules/`
-| The pinned Node toolchain and the installed packages.
-|===
-
-== Layout
-
-[cols="1,2"]
-|===
-| Path | What it is
-
-| `src/main/resources/spa/`
-| The SPA: `index.html`, `app.js`, `app.css`, `landing.html`. No framework, no bundler, no build
-  step -- the served files are the authored files, bind-mounted into the gateway containers.
-
-| `tests/`, `fixtures/`, `utils/`
-| The Playwright suite, its shared fixtures, and the Keycloak login helper.
-
-| `playwright.config.js`
-| Two projects, `session-server` and `session-cookie`, differing only in `baseURL`.
+`integration-user` / `integration-password`. Note the explicit filename -- the gateway serves
+link:doc/integration-sample.adoc#_no_directory_index[no directory index].
 
-| `scripts/`
-| The trimmed bring-up and teardown of exactly three containers.
-|===
+Everything generated sits under `target/` and is git-ignored.
 
 == Further Reading
 
 Both layers are authoritative; this file is only the front door.
 
-* link:../doc/user/demo-client.adoc[Demo Client -- the BFF Integration Sample] -- the *integrator*
+* link:doc/integration-sample.adoc[Demo Client -- the BFF Integration Sample] -- the *integrator*
   layer: the browser-facing contract, the four identity-disclosure states, the same-origin
   `returnUrl` rule, and the `gateway.yaml` a deployment needs to serve its own bundle this way.
-* link:../doc/development/demo-client.adoc[Demo Client and the Playwright End-to-End Suite] -- the
-  *contributor* layer: the module layout, the opt-in build mechanism, the Chromium host-resolver
-  mapping and why it is required, and the standing prohibitions this module carries.
+* link:doc/playwright-suite.adoc[Demo Client and the Playwright End-to-End Suite] -- the
+  *contributor* layer: the link:doc/playwright-suite.adoc#_module_layout[module layout], where a run
+  link:doc/playwright-suite.adoc#_running_the_suite_locally[leaves its results and screenshots], the
+  opt-in build mechanism, the Chromium host-resolver mapping and why it is required, and the standing
+  prohibitions this module carries.
 
 Read the contributor document before changing the suite. Several of its constraints look arbitrary
 and are not.
diff --git a/doc/user/demo-client.adoc b/demo-client/doc/integration-sample.adoc
similarity index 88%
rename from doc/user/demo-client.adoc
rename to demo-client/doc/integration-sample.adoc
index 5c986360..67414e89 100644
--- a/doc/user/demo-client.adoc
+++ b/demo-client/doc/integration-sample.adoc
@@ -9,14 +9,14 @@ four identity-disclosure states an application can reach, the redirect rules the
 your behalf, and the `gateway.yaml` a deployment needs so the gateway serves the application itself.
 
 The runnable sample lives in `demo-client/` (see
-link:../../demo-client/README.adoc[`demo-client/README.adoc`] for the quickstart). How that module is
+link:../README.adoc[`demo-client/README.adoc`] for the quickstart). How that module is
 built, and why its test suite is shaped as it is, is the contributor concern documented in
-link:../development/demo-client.adoc[Demo Client and the Playwright End-to-End Suite].
+link:playwright-suite.adoc[Demo Client and the Playwright End-to-End Suite].
 
 The field-level contract for every key named here is
-link:../configuration.adoc[Configuration Reference]; the setup guides for the two session variants are
-link:bff-session.adoc[Server-Session BFF -- Operator Setup] and
-link:bff-cookie.adoc[Cookie-Based BFF -- Operator Setup]. This document is the *sample*, not a second
+link:../../doc/configuration.adoc[Configuration Reference]; the setup guides for the two session variants are
+link:../../doc/user/bff-session.adoc[Server-Session BFF -- Operator Setup] and
+link:../../doc/user/bff-cookie.adoc[Cookie-Based BFF -- Operator Setup]. This document is the *sample*, not a second
 copy of either.
 
 == The Browser-Facing Contract
@@ -80,6 +80,7 @@ what makes the whole contract reachable with a plain same-origin `fetch`.
 Two properties of this table are worth stating explicitly, because assuming otherwise is the most
 common way to mis-integrate:
 
+[#_the_401_versus_302_split]
 * *The `401`-versus-`302` split is PATH-based, not `Accept`-based.* Both reserved endpoints are
   blind to the request's `Accept` header. `/auth/userinfo` is an XHR probe and answers
   `401 application/problem+json` without a session -- it never redirects, whatever you send. Do not
@@ -104,6 +105,13 @@ The whole leg is navigations the browser performs; your application starts it an
 Tokens never reach the browser at any point: the gateway holds them, and the application's only
 credential is the `HttpOnly` session cookie it cannot read.
 
+image::../../doc/resources/diagrams/demo-client-login-flow.svg[Demo-client login flow as the single-page application sees it, align=center]
+
+The diagram draws only the legs your application participates in. The identity-provider interior --
+the authorization request, the user authenticating, and the gateway's back-channel code exchange --
+is deliberately not redrawn here; it is the same handshake both BFF variants perform, drawn once in
+link:../../doc/resources/diagrams/bff-login-sequence.svg[the BFF login handshake diagram].
+
 [NOTE]
 .What you must configure at the identity provider
 ====
@@ -135,7 +143,7 @@ What this means for you as an integrator: *treat access logs and `Referer`-beari
 callback path as sensitive*, and do not add third-party analytics or error reporting that captures
 full URLs on `/auth/callback`. Nothing else in your application is affected -- the code never
 reaches your code. The full statement is in
-link:../architecture.adoc#_oidc_callback_response_mode[Architecture -- OIDC callback response mode].
+link:../../doc/architecture.adoc#_oidc_callback_response_mode[Architecture -- OIDC callback response mode].
 ====
 
 == The Four Identity-Disclosure States
@@ -171,6 +179,8 @@ Against the sample's `allowed_claims: ["sub", "preferred_username", "email", "gr
   because the operator did not allow it.
 |===
 
+image::../../doc/resources/diagrams/demo-client-userinfo-probe.svg[Demo-client userinfo probe and the four identity-disclosure states, align=center]
+
 The last row is the one to internalise. *The operator -- never the browser -- widens disclosure.* A
 claim outside `allowed_claims` can never be disclosed even when the identity provider issued it, and
 naming one explicitly is rejected `403` before any disclosure happens. An empty allowlist discloses
@@ -219,11 +229,12 @@ with a live session redirects straight to the validated return URL. No new login
 started and no binding cookie is set. An application may therefore link to `/auth/login`
 unconditionally without worrying about spurious re-authentication.
 
+[#_serving_your_application_from_the_gateway]
 == Serving Your Application from the Gateway
 
 The sample is served through the asset terminal action
-(link:../adr/0014-asset-serving-terminal-action.adoc[ADR-0014]) under a `type: asset` /
-`access: public` anchor (link:../adr/0013-anchor-type-access-axes.adoc[ADR-0013]). The route is one
+(link:../../doc/adr/0014-asset-serving-terminal-action.adoc[ADR-0014]) under a `type: asset` /
+`access: public` anchor (link:../../doc/adr/0013-anchor-type-access-axes.adoc[ADR-0013]). The route is one
 block:
 
 [source,yaml]
@@ -249,7 +260,7 @@ Three things a deployment needs, and one it does not:
 * You do *not* need a new anchor per bundle. Reusing an existing `access: public` asset anchor keeps
   the anchor set -- which must stay pairwise prefix-disjoint -- unchanged.
 
-[IMPORTANT]
+[IMPORTANT#_no_directory_index]
 ====
 *There is no directory index.* A request for `/assets/demo/` without a filename returns `404`. Every
 entry point must name a concrete file: `/assets/demo/index.html`, not `/assets/demo/`. This applies
@@ -327,5 +338,9 @@ The sample runs unchanged against both session variants -- `session.mode: server
 
 That is the intended property. An application is written against the reserved-path contract, and the
 operator chooses the session variant on operational grounds
-(link:bff-session.adoc[server-session setup], link:bff-cookie.adoc[cookie setup]) without the
+(link:../../doc/user/bff-session.adoc[server-session setup], link:../../doc/user/bff-cookie.adoc[cookie setup]) without the
 application knowing which was chosen.
+
+You are not asked to take that on trust: the Playwright suite runs the same specs against both
+variants, which is what makes "browser-observably identical" an executable assertion rather than a
+claim. link:playwright-suite.adoc#_why_the_demo_exists[Why the Demo Exists] records the mechanism.
diff --git a/doc/development/demo-client.adoc b/demo-client/doc/playwright-suite.adoc
similarity index 87%
rename from doc/development/demo-client.adoc
rename to demo-client/doc/playwright-suite.adoc
index 85f6de61..27f90aaf 100644
--- a/doc/development/demo-client.adoc
+++ b/demo-client/doc/playwright-suite.adoc
@@ -11,8 +11,8 @@ only forms that work against this gateway, and this document records which.
 
 The operator- and integrator-facing view -- the browser-facing contract, the claim views, the asset
 anchor an integrator declares in their own `gateway.yaml` -- is
-link:../user/demo-client.adoc[Demo Client -- Integration Sample]. The module's one-screen quickstart
-is link:../../demo-client/README.adoc[`demo-client/README.adoc`]. This document does not restate
+link:integration-sample.adoc[Demo Client -- Integration Sample]. The module's one-screen quickstart
+is link:../README.adoc[`demo-client/README.adoc`]. This document does not restate
 either.
 
 [IMPORTANT]
@@ -23,6 +23,7 @@ executable, and the asset route that serves it lives in the `integration-tests`
 configuration -- not in any production example. See <<_the_demo_is_excluded_from_the_production_image>>.
 ====
 
+[#_why_the_demo_exists]
 == Why the Demo Exists
 
 The gateway's server-session and cookie-session BFF variants expose a browser-facing contract:
@@ -44,6 +45,16 @@ session modes -- `session.mode: server` on port 10443 and `session.mode: cookie`
 as two Playwright projects that differ only in `baseURL`. "The two variants are browser-observably
 identical" stops being a claim in a design document and becomes an executable assertion.
 
+The logout round-trip is the clearest example of what only a browser can assert. The suite drives the
+whole navigation chain and then re-probes the info endpoint, because the `401` -- not the landing page
+rendering -- is what proves the session is gone:
+
+image::../../doc/resources/diagrams/demo-client-logout-flow.svg[Demo-client logout round-trip and the 401 re-probe that proves it, align=center]
+
+Note where the authoritative step sits: the gateway destroys the local session *before* any
+identity-provider leg, so the elided round-trip cannot leave a usable local session behind even when
+it fails outright.
+
 [[_why_the_java_it_suite_could_not_catch_it]]
 === The first gap was not hypothetical -- it hid a real, total login failure
 
@@ -58,7 +69,7 @@ Lax cookie is not sent on a cross-site POST*. A real browser therefore arrived a
 without the binding cookie and was rejected `403` on the callback's "no browser-binding cookie"
 branch. Every login. The fix was to drive `response_mode=query` so the callback is a top-level GET
 navigation, on which a Lax cookie *is* sent -- see
-link:../architecture.adoc#_oidc_callback_response_mode[Architecture -- OIDC callback response mode]
+link:../../doc/architecture.adoc#_oidc_callback_response_mode[Architecture -- OIDC callback response mode]
 for the mode, the rejected `SameSite=None` alternative, and the accepted code-in-URL tradeoff.
 
 [IMPORTANT]
@@ -77,6 +88,7 @@ it. That limitation is now recorded on `BffKeycloakLoginFlow` itself, so the nex
 the helper rather than in this document.
 ====
 
+[#_module_layout]
 == Module Layout
 
 `demo-client/` is a Maven module with `<packaging>pom</packaging>` and no Java. Every Java plugin is
@@ -124,7 +136,7 @@ Maven-standard source path even though no Maven plugin processes them.
 == Why the Gateway Serves the SPA
 
 The SPA is served *by the gateway itself*, through the `type: asset` / `access: public` terminal
-action decided in link:../adr/0014-asset-serving-terminal-action.adoc[ADR-0014]. It is not served by
+action decided in link:../../doc/adr/0014-asset-serving-terminal-action.adoc[ADR-0014]. It is not served by
 a side-car static-file container, and that is the load-bearing decision in the whole module.
 
 *Same-origin is what makes the contract observable.* The gateway's reserved paths are exact-match
@@ -139,13 +151,16 @@ of it.
 
 Two consequences follow, and both are landed behaviour rather than demo choices:
 
-* The gateway owns the response envelope. It sets the `Content-Type` from the file extension, adds
-  `X-Content-Type-Options: nosniff`, and strips any `Set-Cookie`. The SPA therefore needs no inline
-  `<script>` and uses none -- `app.css` and `app.js` load as plain relative assets.
-* `DirectoryAssetSource` performs *no* directory-index resolution. `/assets/demo/` without a
-  filename returns `404`. Every entry point in the SPA, in this documentation, in the suite, and in
-  the gateway's `final_redirect` therefore names a concrete file -- `index.html` or `landing.html`
-  -- explicitly. This is not a bug to fix inside the demo.
+* The gateway owns the response envelope -- what it sets, and what the served content cannot
+  override, is stated for integrators in
+  link:integration-sample.adoc#_serving_your_application_from_the_gateway[Serving Your Application
+  from the Gateway]. The consequence here is that the SPA needs no inline `<script>` and uses none --
+  `app.css` and `app.js` load as plain relative assets.
+* `DirectoryAssetSource` performs *no* directory-index resolution
+  (link:integration-sample.adoc#_no_directory_index[the rule, stated for integrators]). Every entry
+  point in the SPA, in this documentation, in the suite, and in the gateway's `final_redirect`
+  therefore names a concrete file -- `index.html` or `landing.html` -- explicitly. This is not a bug
+  to fix inside the demo.
 
 This module is also the asset action's *first consumer outside the asset package's own tests*, which
 is a deliberate part of its value: it exercises the feature the way a deployment would.
@@ -223,29 +238,12 @@ Base URLs, the Keycloak host URL and `PW_TEST_HTML_REPORT_OPEN=never` are passed
 execution as environment, sourced from POM properties. *No port number is restated inside
 JavaScript* -- when a published port changes, it changes in one place.
 
+[#_running_the_suite_locally]
 == Running the Suite Locally
 
-Prerequisites: Docker with Compose, and a built `api-sheriff:distroless` native image.
-
-The full run, from a clean tree:
-
-[source,bash]
-----
-python3 .plan/execute-script.py plan-marshall:build-maven:maven \
-  run --command-args "verify -Pe2e-demo -pl demo-client"
-----
-
-That single command installs the toolchain, lints, brings up the three containers, runs both
-Playwright projects, and tears the stack down again.
-
-When iterating on specs it is faster to hold the stack up and re-run only the tests:
-
-[source,bash]
-----
-demo-client/scripts/start-dev-environment.sh
-cd demo-client && npm run test
-demo-client/scripts/stop-dev-environment.sh
-----
+The prerequisites, the one full-run command and the faster iterate loop are the module quickstart and
+live in link:../README.adoc[`demo-client/README.adoc`]. This section is what that quickstart leaves
+out: why those commands behave as they do, and what they leave behind.
 
 [WARNING]
 ====
@@ -270,7 +268,9 @@ script prints is built from the same derived rows rather than from a second copy
 goal aborts the build immediately on a non-zero exit, so Maven never reaches `post-integration-test`
 and its teardown does not run. That is the useful behaviour for a developer -- the stack you need
 for diagnosis is still there. Tear it down with `demo-client/scripts/stop-dev-environment.sh` when
-you are done, or run any `clean` build, whose `pre-clean` teardown does it for you.
+you are done, or run a `clean` build under the profile (`./mvnw clean -Pe2e-demo -pl demo-client`),
+whose `pre-clean` teardown does it for you. The teardown execution is declared inside the `e2e-demo`
+profile, so a plain `clean` without the profile tears nothing down.
 
 CI is the opposite case: an abandoned stack there holds fixed host ports for the next run, so
 `.github/workflows/demo-client-e2e.yml` carries an `if: always()` teardown step.
@@ -325,11 +325,12 @@ later reader does not re-derive it -- or worse, reverse it.
 *No test may send `Accept: text/html` to the info endpoint expecting `302` -- the 401-vs-302 split
 is PATH-based.*
 
-Both reserved endpoints are `Accept`-blind. `/auth/userinfo` is an XHR probe: with no live session
-it answers `401 application/problem+json`, *never* a redirect, whatever the request's `Accept`
-header says. `/auth/login` always answers `302`. Which of the two a caller gets is determined by
-*which path it called*, not by content negotiation. No spec may assert that the info endpoint varies
-on `Accept`, and none may send an `Accept` header to it expecting a redirect.
+The contract itself -- that both reserved endpoints are `Accept`-blind, and that which of the two
+answers a caller gets is determined by *which path it called* rather than by content negotiation --
+is stated for integrators in
+link:integration-sample.adoc#_the_401_versus_302_split[Demo Client -- Integration Sample]. The
+prohibition this section carries is the testing consequence: no spec may assert that the info
+endpoint varies on `Accept`, and none may send an `Accept` header to it expecting a redirect.
 
 This prohibition is recorded verbatim because a superseded framing described the split as
 `Accept`-driven, and a test written against that framing would pass for the wrong reason on the
@@ -426,7 +427,7 @@ It is deliberately not attached to any `pull_request` trigger and is not added t
 The demo adds a bind mount to two services in `integration-tests/docker-compose.yml`, and one
 `de.cuioss.sheriff.management-scheme` label to `keycloak` so the bring-up derives that service's
 readiness probe from the model exactly as it derives the gateways'. The
-link:integration-test-topology.adoc[Integration-Test Topology] document draws the mounted material of
+link:../../doc/development/integration-test-topology.adoc[Integration-Test Topology] document draws the mounted material of
 that stack and states that a change to `docker-compose.yml` makes its diagram stale. When the demo
 mount changes shape -- a different host path, a third instance, a second mounted directory -- update
 that diagram in the same change rather than annotating it.
diff --git a/demo-client/pom.xml b/demo-client/pom.xml
index 43708346..74aa0a2e 100644
--- a/demo-client/pom.xml
+++ b/demo-client/pom.xml
@@ -21,7 +21,7 @@
     <!-- This module carries NO Java. It exists to own the demo SPA sources, the Playwright suite and the
          npm toolchain that runs them. Everything npm-related lives inside the 'e2e-demo' profile below,
          so a default reactor build of this module is a genuine no-op: no Node download, no npm install,
-         no container, no artifact. See doc/development/demo-client.adoc for the full rationale. -->
+         no container, no artifact. See doc/playwright-suite.adoc for the full rationale. -->
 
     <dependencies />
 
@@ -142,7 +142,7 @@
                                      the containers left up for. Making the local path tear down
                                      unconditionally would destroy the logs of the failure being
                                      diagnosed. This is a decision, not an omission; it is documented
-                                     for developers in doc/development/demo-client.adoc. -->
+                                     for developers in doc/playwright-suite.adoc. -->
                             <execution>
                                 <id>stop-dev-environment-post-integration-test</id>
                                 <phase>post-integration-test</phase>
diff --git a/doc/development/README.adoc b/doc/development/README.adoc
index b7cea279..64ad7f1e 100644
--- a/doc/development/README.adoc
+++ b/doc/development/README.adoc
@@ -76,7 +76,7 @@ This tree is seeded here and grows as contributor-facing material lands.
   certificate and configuration material, and the two trust boundaries -- drawn from
   `docker-compose.yml` and the mounted `gateway.yaml`, which stay the authoritative sources.
 
-| link:demo-client.adoc[Demo Client and the Playwright End-to-End Suite]
+| link:../../demo-client/doc/playwright-suite.adoc[Demo Client and the Playwright End-to-End Suite]
 | The `demo-client` module -- why the demo SPA is served by the gateway rather than a side-car
   static server, the opt-in `skipPlaywrightTests` / `e2e-demo` build mechanism that keeps it out of
   the default lane, how to run the suite locally, the Chromium host-resolver mapping the pinned
diff --git a/doc/resources/diagrams/demo-client-login-flow.svg b/doc/resources/diagrams/demo-client-login-flow.svg
new file mode 100644
index 00000000..816fe6a7
--- /dev/null
+++ b/doc/resources/diagrams/demo-client-login-flow.svg
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Demo-client login flow — the SPA-facing legs only. The identity-provider
+  interior is deliberately elided and cross-referenced to
+  bff-login-sequence.svg rather than redrawn. Time flows downward.
+  theme-handling: A (theme-neutral)
+  see  pm-documents:ref-svg-diagrams/standards/diagram-type-sequence.md
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 630"
+     role="img" aria-labelledby="title desc"
+     font-family="ui-sans-serif, -apple-system, system-ui, 'Segoe UI', sans-serif">
+  <title id="title">Demo-client login flow as the single-page application sees it</title>
+  <desc id="desc">A time-ordered exchange showing only the legs the demo single-page application participates in. The application hands the login to the browser with a top-level navigation to /auth/login carrying a same-origin returnUrl; API Sheriff sets a short-lived SameSite=Lax browser-binding cookie and redirects to the identity provider. The identity-provider authorization and server-to-server code exchange are elided and cross-referenced to the BFF login handshake diagram. The browser returns to /auth/callback as a top-level GET, the gateway sets the HttpOnly session cookie and redirects to the validated returnUrl, and the reloaded application confirms its state with a same-origin fetch of /auth/userinfo.</desc>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="9" markerHeight="9" orient="auto">
+      <path d="M0,0 L10,5 L0,10 z" class="arrow-fill"/>
+    </marker>
+    <style>
+      .col-header   { font-size: 15px; font-weight: 600; fill: #6e7681; text-anchor: middle; }
+      .stroke       { stroke: #6e7681; stroke-width: 1.2; fill: none; }
+      .sep          { stroke: #6e7681; stroke-width: 0.6; stroke-dasharray: 3 3; }
+      .arrow        { stroke: #6e7681; stroke-width: 1.5; fill: none; }
+      .arrow-return { stroke: #6e7681; stroke-width: 1.5; fill: none; stroke-dasharray: 5 4; }
+      .arrow-fill   { fill: #6e7681; }
+      .arrow-lbl    { font-size: 11px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+      .activation   { stroke: #6e7681; stroke-width: 0.8; fill: #6e7681; opacity: 0.15; }
+      .caption      { font-size: 12px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+      .ref-frame    { stroke: #6e7681; stroke-width: 0.6; stroke-dasharray: 3 3; fill: none; }
+    </style>
+  </defs>
+
+  <!-- actors + lifelines -->
+  <text x="140" y="30" class="col-header">Demo SPA</text>
+  <rect class="stroke" x="80" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="140" y1="80" x2="140" y2="560"/>
+
+  <text x="500" y="30" class="col-header">Browser</text>
+  <rect class="stroke" x="440" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="500" y1="80" x2="500" y2="560"/>
+
+  <text x="860" y="30" class="col-header">API Sheriff</text>
+  <rect class="stroke" x="800" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="860" y1="80" x2="860" y2="560"/>
+
+  <!-- activation bars -->
+  <rect class="activation" x="855" y="156" width="10" height="56"/>
+  <rect class="activation" x="855" y="340" width="10" height="56"/>
+  <rect class="activation" x="855" y="472" width="10" height="56"/>
+
+  <!-- 1. SPA hands the login to the browser -->
+  <line class="arrow" x1="140" y1="120" x2="495" y2="120" marker-end="url(#arrow)"/>
+  <text x="320" y="112" class="arrow-lbl">window.location.assign('/auth/login?returnUrl=&#8230;')</text>
+
+  <!-- 2. browser -> gateway (top-level navigation) -->
+  <line class="arrow" x1="500" y1="164" x2="855" y2="164" marker-end="url(#arrow)"/>
+  <text x="680" y="156" class="arrow-lbl">GET /auth/login?returnUrl=&#8230; (top-level navigation)</text>
+
+  <!-- 3. gateway -> browser 302 to IdP -->
+  <line class="arrow-return" x1="855" y1="208" x2="500" y2="208" marker-end="url(#arrow)"/>
+  <text x="680" y="200" class="arrow-lbl">302 &#8594; IdP /authorize &#183; binding cookie (SameSite=Lax)</text>
+
+  <!-- elided IdP interior: ref frame spanning exactly the browser-gateway gutter -->
+  <rect class="ref-frame" x="500" y="240" width="360" height="72" rx="6"/>
+  <text x="680" y="262" class="arrow-lbl">IdP authorization and user authentication</text>
+  <text x="680" y="280" class="arrow-lbl">server-to-server code exchange</text>
+  <text x="680" y="298" class="arrow-lbl">not redrawn &#8212; see bff-login-sequence.svg</text>
+
+  <!-- 4. browser -> gateway callback -->
+  <line class="arrow" x1="500" y1="348" x2="855" y2="348" marker-end="url(#arrow)"/>
+  <text x="680" y="340" class="arrow-lbl">GET /auth/callback?code&amp;state (top-level GET)</text>
+
+  <!-- 5. gateway -> browser: session cookie + return to app -->
+  <line class="arrow-return" x1="855" y1="392" x2="500" y2="392" marker-end="url(#arrow)"/>
+  <text x="680" y="384" class="arrow-lbl">302 &#8594; validated returnUrl &#183; Set-Cookie (HttpOnly)</text>
+
+  <!-- 6. browser reloads the SPA -->
+  <line class="arrow-return" x1="495" y1="436" x2="140" y2="436" marker-end="url(#arrow)"/>
+  <text x="320" y="428" class="arrow-lbl">SPA re-loads at returnUrl</text>
+
+  <!-- 7. SPA confirms its state -->
+  <line class="arrow" x1="140" y1="480" x2="855" y2="480" marker-end="url(#arrow)"/>
+  <text x="680" y="472" class="arrow-lbl">fetch('/auth/userinfo')</text>
+
+  <!-- 8. gateway -> SPA -->
+  <line class="arrow-return" x1="855" y1="524" x2="140" y2="524" marker-end="url(#arrow)"/>
+  <text x="680" y="516" class="arrow-lbl">200 &#183; claims + session &#183; no-store</text>
+
+  <!-- footer -->
+  <text x="500" y="594" class="caption">Tokens never reach the browser. The gateway holds them; the SPA's only credential is the HttpOnly session cookie.</text>
+  <text x="500" y="612" class="caption">returnUrl is validated same-origin &#8212; an off-origin or unparseable value silently falls back to the gateway default.</text>
+</svg>
diff --git a/doc/resources/diagrams/demo-client-logout-flow.svg b/doc/resources/diagrams/demo-client-logout-flow.svg
new file mode 100644
index 00000000..f6300506
--- /dev/null
+++ b/doc/resources/diagrams/demo-client-logout-flow.svg
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Demo-client logout flow — the SPA-facing legs only. The identity-provider
+  end-session round-trip is deliberately elided rather than redrawn.
+  Time flows downward.
+  theme-handling: A (theme-neutral)
+  see  pm-documents:ref-svg-diagrams/standards/diagram-type-sequence.md
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 710"
+     role="img" aria-labelledby="title desc"
+     font-family="ui-sans-serif, -apple-system, system-ui, 'Segoe UI', sans-serif">
+  <title id="title">Demo-client logout round-trip and the 401 re-probe that proves it</title>
+  <desc id="desc">A time-ordered exchange showing the logout legs the demo single-page application participates in. The application hands the logout to the browser as a top-level navigation to /auth/logout. API Sheriff destroys the server-side session and clears the session cookie as the authoritative step before any identity-provider leg, then redirects to the end-session endpoint. The provider round-trip is elided and returns the browser to the state-verified /auth/logout/return, from which the gateway redirects to the configured final_redirect naming a concrete public file. A final same-origin fetch of /auth/userinfo answering 401 is the authoritative proof the session is gone; a rendered landing page proves only that a static file was served.</desc>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="9" markerHeight="9" orient="auto">
+      <path d="M0,0 L10,5 L0,10 z" class="arrow-fill"/>
+    </marker>
+    <style>
+      .col-header   { font-size: 15px; font-weight: 600; fill: #6e7681; text-anchor: middle; }
+      .stroke       { stroke: #6e7681; stroke-width: 1.2; fill: none; }
+      .sep          { stroke: #6e7681; stroke-width: 0.6; stroke-dasharray: 3 3; }
+      .arrow        { stroke: #6e7681; stroke-width: 1.5; fill: none; }
+      .arrow-return { stroke: #6e7681; stroke-width: 1.5; fill: none; stroke-dasharray: 5 4; }
+      .arrow-fill   { fill: #6e7681; }
+      .arrow-lbl    { font-size: 11px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+      .activation   { stroke: #6e7681; stroke-width: 0.8; fill: #6e7681; opacity: 0.15; }
+      .note-end     { font-size: 11px; fill: #6e7681; text-anchor: end; font-style: italic; }
+      .caption      { font-size: 12px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+      .ref-frame    { stroke: #6e7681; stroke-width: 0.6; stroke-dasharray: 3 3; fill: none; }
+    </style>
+  </defs>
+
+  <!-- actors + lifelines -->
+  <text x="140" y="30" class="col-header">Demo SPA</text>
+  <rect class="stroke" x="80" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="140" y1="80" x2="140" y2="640"/>
+
+  <text x="500" y="30" class="col-header">Browser</text>
+  <rect class="stroke" x="440" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="500" y1="80" x2="500" y2="640"/>
+
+  <text x="860" y="30" class="col-header">API Sheriff</text>
+  <rect class="stroke" x="800" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="860" y1="80" x2="860" y2="640"/>
+
+  <!-- activation bars -->
+  <rect class="activation" x="855" y="156" width="10" height="112"/>
+  <rect class="activation" x="855" y="378" width="10" height="56"/>
+  <rect class="activation" x="855" y="466" width="10" height="56"/>
+  <rect class="activation" x="855" y="554" width="10" height="56"/>
+
+  <!-- 1. SPA hands the logout to the browser -->
+  <line class="arrow" x1="140" y1="120" x2="495" y2="120" marker-end="url(#arrow)"/>
+  <text x="320" y="112" class="arrow-lbl">window.location.assign('/auth/logout')</text>
+
+  <!-- 2. browser -> gateway -->
+  <line class="arrow" x1="500" y1="164" x2="855" y2="164" marker-end="url(#arrow)"/>
+  <text x="680" y="156" class="arrow-lbl">GET /auth/logout (top-level navigation)</text>
+
+  <!-- gateway note: the authoritative local step, anchored inside the gutter -->
+  <text x="844" y="196" class="note-end">destroy server-side session</text>
+  <text x="844" y="212" class="note-end">clear session cookie</text>
+  <text x="844" y="228" class="note-end">(authoritative, before any IdP leg)</text>
+
+  <!-- 3. gateway -> browser 302 to end-session -->
+  <line class="arrow-return" x1="855" y1="264" x2="500" y2="264" marker-end="url(#arrow)"/>
+  <text x="680" y="256" class="arrow-lbl">302 &#8594; IdP end-session endpoint</text>
+
+  <!-- elided IdP end-session round-trip -->
+  <rect class="ref-frame" x="500" y="296" width="360" height="54" rx="6"/>
+  <text x="680" y="318" class="arrow-lbl">IdP end-session round-trip &#8212; not redrawn</text>
+  <text x="680" y="336" class="arrow-lbl">the browser returns to /auth/logout/return</text>
+
+  <!-- 4. browser -> gateway logout return -->
+  <line class="arrow" x1="500" y1="386" x2="855" y2="386" marker-end="url(#arrow)"/>
+  <text x="680" y="378" class="arrow-lbl">GET /auth/logout/return?state (state-verified)</text>
+
+  <!-- 5. gateway -> browser final_redirect -->
+  <line class="arrow-return" x1="855" y1="430" x2="500" y2="430" marker-end="url(#arrow)"/>
+  <text x="680" y="422" class="arrow-lbl">302 &#8594; final_redirect: /assets/demo/landing.html</text>
+
+  <!-- 6. browser fetches the public landing page -->
+  <line class="arrow" x1="500" y1="474" x2="855" y2="474" marker-end="url(#arrow)"/>
+  <text x="680" y="466" class="arrow-lbl">GET /assets/demo/landing.html (a concrete file)</text>
+
+  <!-- 7. gateway -> browser 200 public asset -->
+  <line class="arrow-return" x1="855" y1="518" x2="500" y2="518" marker-end="url(#arrow)"/>
+  <text x="680" y="510" class="arrow-lbl">200 &#183; public asset, no session required</text>
+
+  <!-- 8. the authoritative re-probe -->
+  <line class="arrow" x1="140" y1="562" x2="855" y2="562" marker-end="url(#arrow)"/>
+  <text x="680" y="554" class="arrow-lbl">fetch('/auth/userinfo') &#8212; the re-probe that proves it</text>
+
+  <!-- 9. gateway -> SPA 401 -->
+  <line class="arrow-return" x1="855" y1="606" x2="140" y2="606" marker-end="url(#arrow)"/>
+  <text x="680" y="598" class="arrow-lbl">401 &#183; the session is gone</text>
+
+  <!-- footer -->
+  <text x="500" y="672" class="caption">The local session is destroyed first, so a logout carrying no live session is already logged out.</text>
+  <text x="500" y="690" class="caption">Treat the 401 re-probe as the proof of logout &#8212; a rendered landing page proves only that a file was served.</text>
+</svg>
diff --git a/doc/resources/diagrams/demo-client-userinfo-probe.svg b/doc/resources/diagrams/demo-client-userinfo-probe.svg
new file mode 100644
index 00000000..67f3e72b
--- /dev/null
+++ b/doc/resources/diagrams/demo-client-userinfo-probe.svg
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Demo-client /auth/userinfo probe — the XHR identity probe and the four
+  identity-disclosure states the claims parameter selects. Time flows downward.
+  theme-handling: A (theme-neutral)
+  see  pm-documents:ref-svg-diagrams/standards/diagram-type-sequence.md
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 640"
+     role="img" aria-labelledby="title desc"
+     font-family="ui-sans-serif, -apple-system, system-ui, 'Segoe UI', sans-serif">
+  <title id="title">Demo-client userinfo probe and the four identity-disclosure states</title>
+  <desc id="desc">A time-ordered exchange between the demo single-page application and API Sheriff over the reserved /auth/userinfo path. Without a session the probe answers 401 application/problem+json and never redirects. With a live session the claims query parameter selects one of four outcomes: omitted yields the curated default view of sub and preferred_username, an explicit list yields only the named claims, an asterisk yields the full operator-allowlisted view, and a claim outside the allowlist is refused 403 even though the identity provider issued it. Every response carries Cache-Control no-store.</desc>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="9" markerHeight="9" orient="auto">
+      <path d="M0,0 L10,5 L0,10 z" class="arrow-fill"/>
+    </marker>
+    <style>
+      .col-header   { font-size: 15px; font-weight: 600; fill: #6e7681; text-anchor: middle; }
+      .stroke       { stroke: #6e7681; stroke-width: 1.2; fill: none; }
+      .sep          { stroke: #6e7681; stroke-width: 0.6; stroke-dasharray: 3 3; }
+      .arrow        { stroke: #6e7681; stroke-width: 1.5; fill: none; }
+      .arrow-return { stroke: #6e7681; stroke-width: 1.5; fill: none; stroke-dasharray: 5 4; }
+      .arrow-fill   { fill: #6e7681; }
+      .arrow-lbl    { font-size: 11px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+      .activation   { stroke: #6e7681; stroke-width: 0.8; fill: #6e7681; opacity: 0.15; }
+      .caption      { font-size: 12px; fill: #6e7681; text-anchor: middle; font-style: italic; }
+    </style>
+  </defs>
+
+  <!-- actors + lifelines -->
+  <text x="175" y="30" class="col-header">Demo SPA</text>
+  <rect class="stroke" x="115" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="175" y1="80" x2="175" y2="560"/>
+
+  <text x="525" y="30" class="col-header">API Sheriff</text>
+  <rect class="stroke" x="465" y="42" width="120" height="36" rx="6"/>
+  <line class="sep" x1="525" y1="80" x2="525" y2="560"/>
+
+  <!-- activation bars: one per exchange -->
+  <rect class="activation" x="520" y="112" width="10" height="48"/>
+  <rect class="activation" x="520" y="224" width="10" height="48"/>
+  <rect class="activation" x="520" y="308" width="10" height="48"/>
+  <rect class="activation" x="520" y="392" width="10" height="48"/>
+  <rect class="activation" x="520" y="476" width="10" height="48"/>
+
+  <!-- 1. anonymous probe -->
+  <line class="arrow" x1="175" y1="120" x2="520" y2="120" marker-end="url(#arrow)"/>
+  <text x="350" y="112" class="arrow-lbl">fetch('/auth/userinfo') &#183; no session</text>
+  <line class="arrow-return" x1="520" y1="156" x2="175" y2="156" marker-end="url(#arrow)"/>
+  <text x="350" y="148" class="arrow-lbl">401 application/problem+json &#183; never a redirect</text>
+
+  <!-- session boundary -->
+  <text x="350" y="200" class="caption">&#8212; after a completed login: the HttpOnly session cookie rides on every same-origin fetch &#8212;</text>
+
+  <!-- 2. curated default view -->
+  <line class="arrow" x1="175" y1="232" x2="520" y2="232" marker-end="url(#arrow)"/>
+  <text x="350" y="224" class="arrow-lbl">fetch('/auth/userinfo')</text>
+  <line class="arrow-return" x1="520" y1="268" x2="175" y2="268" marker-end="url(#arrow)"/>
+  <text x="350" y="260" class="arrow-lbl">200 &#183; sub, preferred_username + session</text>
+
+  <!-- 3. explicit selection -->
+  <line class="arrow" x1="175" y1="316" x2="520" y2="316" marker-end="url(#arrow)"/>
+  <text x="350" y="308" class="arrow-lbl">fetch('/auth/userinfo?claims=email')</text>
+  <line class="arrow-return" x1="520" y1="352" x2="175" y2="352" marker-end="url(#arrow)"/>
+  <text x="350" y="344" class="arrow-lbl">200 &#183; email only</text>
+
+  <!-- 4. full allowlisted view -->
+  <line class="arrow" x1="175" y1="400" x2="520" y2="400" marker-end="url(#arrow)"/>
+  <text x="350" y="392" class="arrow-lbl">fetch('/auth/userinfo?claims=*')</text>
+  <line class="arrow-return" x1="520" y1="436" x2="175" y2="436" marker-end="url(#arrow)"/>
+  <text x="350" y="428" class="arrow-lbl">200 &#183; sub, preferred_username, email, groups</text>
+
+  <!-- 5. allowlist cap -->
+  <line class="arrow" x1="175" y1="484" x2="520" y2="484" marker-end="url(#arrow)"/>
+  <text x="350" y="476" class="arrow-lbl">fetch('/auth/userinfo?claims=given_name')</text>
+  <line class="arrow-return" x1="520" y1="520" x2="175" y2="520" marker-end="url(#arrow)"/>
+  <text x="350" y="512" class="arrow-lbl">403 &#183; claim outside the operator allowlist</text>
+
+  <!-- footer -->
+  <text x="350" y="592" class="caption">Every response &#8212; 200, 401 and 403 alike &#8212; carries Cache-Control: no-store.</text>
+  <text x="350" y="610" class="caption">The 401-vs-302 split is path-based: this endpoint never redirects, whatever Accept says.</text>
+</svg>
diff --git a/doc/user/README.adoc b/doc/user/README.adoc
index 6cbdb537..da71e85b 100644
--- a/doc/user/README.adoc
+++ b/doc/user/README.adoc
@@ -55,7 +55,7 @@ layer.
   do in this variant, the login-leg session affinity, and the forced re-login on a sealed-cookie
   format bump. Links to the Configuration Reference for the `oidc` key contract.
 
-| link:demo-client.adoc[Demo Client -- the BFF Integration Sample]
+| link:../../demo-client/doc/integration-sample.adoc[Demo Client -- the BFF Integration Sample]
 | The copy-this sample for putting a browser application behind a BFF gateway: the browser-facing
   contract of the reserved `/auth` paths, the four identity-disclosure states the `claims` parameter
   selects (including the `403` an operator-disallowed claim earns), the same-origin `returnUrl` rule
diff --git a/integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/BffKeycloakLoginFlow.java b/integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/BffKeycloakLoginFlow.java
index d8357a83..925abd8f 100644
--- a/integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/BffKeycloakLoginFlow.java
+++ b/integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/BffKeycloakLoginFlow.java
@@ -45,7 +45,7 @@
  * dead-ends on the {@code 403} "no browser-binding cookie" branch. That is precisely the defect a
  * green run of this suite failed to reveal. <em>Do not read a green IT suite as proof that the
  * browser flow works.</em> The browser-level proof lives in the demo-client Playwright suite, which
- * drives a real Chromium with a real cookie jar; see {@code doc/development/demo-client.adoc}.
+ * drives a real Chromium with a real cookie jar; see {@code demo-client/doc/playwright-suite.adoc}.
  * <p>
  * <strong>Container-network rewrite.</strong> The {@code integration} realm pins
  * {@code frontendUrl https://keycloak:8443}, so every authorization / login-form URL the gateway or