docs: move experiments out of README

2 files changed, 45 insertions, 46 deletions

diff --git a/README.md b/README.md
index cf7af05..a8da10c 100644
--- a/README.md
+++ b/README.md
@@ -52,9 +52,9 @@ scenarios. The following organizational hierarchy is demonstrated here:
 ```
 Organization(name: "default")
   * Group(name: "A")
-    * Project(name: "A1"
+    * Project(name: "A1")
   * Group(name: "B")
-    * Project(name: "B1"
+    * Project(name: "B1")
 Organization(name: "gitlab")
   * Group(name: "gitlab-org")
     * Project(name: "gitlab")
@@ -93,47 +93,7 @@ Organization(name: "gitlab")
     $ mage
     ```
 
-1. Open a browser to `http://ui.example.com:8080/saml/new` to start a new SAML
-   session. Or open `http://ui.example.com:8080/oidc/new` to start a new OIDC
-   session.
-
-## Experiments
-
-### Twirp + gRPC (AuthZ)
-
-This experiment exposes a gRPC endpoint that aligns with the [`Ability.allowed?(subject, permission, resource)`][1] interface from GitLab's declarative authorization logic.
-
-It demonstrates a headless authorization service that provides a low-latency decision point for other services to verify permissions.
-
-Actors in this experiment:
-
-* Headless authz service: A facade over GitLab’s existing declarative policies.
-* API (Resource Server in OAuth terms): A slimmed-down GitLab REST API that delegates authorization decisions to the authz service.
-
-### SAML, OIDC, OAuth
-
-This experiment showcases how a separate authx service can handle both authentication and authorization using standard protocols:
-
-* SAML & OIDC for authentication
-* OAuth for authorization
-
-Actors in this experiment:
-
-* Authx service: Acts as a SAML Identity Provider and an OAuth Authorization Server.
-* API: A slimmed-down GitLab REST API.
-
-### API Gateway
-
-This experiment explores a stateless authorization mechanism by integrating a policy DSL (such as [Casbin][3]) into a reverse proxy.
-Authorization decisions are made early in the request pipeline based on HTTP request headers and body content.
-
-### Sidecar Process
-
-This experiment demonstrates a sidecar approach for making authorization decisions within an nginx process.
-Inspired by [Open Policy Agent][4] deployments. This experiment:
-
-* Uses lua bindings in nginx to connect to a local client process.
-* The client process proxies requests to a gRPC based policy decision service.
+1. Open a browser to `http://ui.example.com:8080/`.
 
 ## Questions
 
@@ -146,10 +106,7 @@ See the [FAQ][9]
 * [protocol buffers][7]
 * [twirp][8]
 
-[1]: https://gitlab.com/gitlab-org/gitlab/-/blob/e1f6db024561e35462ac8d9f54b8f9678f6ed6ee/app/models/ability.rb#L73
 [2]: https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/policies
-[3]: https://casbin.org/
-[4]: https://www.openpolicyagent.org/
 [5]: https://tip.golang.org/doc/modules/managing-dependencies#tools
 [6]: https://grpc.io/docs/
 [7]: https://protobuf.dev/programming-guides/proto3/
diff --git a/doc/share/authz/EXPERIMENT.md b/doc/share/authz/EXPERIMENT.md
new file mode 100644
index 0000000..0460fe3
--- /dev/null
+++ b/doc/share/authz/EXPERIMENT.md
@@ -0,0 +1,42 @@
+## Experiments
+
+### Twirp + gRPC (AuthZ)
+
+This experiment exposes a gRPC endpoint that aligns with the [`Ability.allowed?(subject, permission, resource)`][1] interface from GitLab's declarative authorization logic.
+
+It demonstrates a headless authorization service that provides a low-latency decision point for other services to verify permissions.
+
+Actors in this experiment:
+
+* Headless authz service: A facade over GitLab’s existing declarative policies.
+* API (Resource Server in OAuth terms): A slimmed-down GitLab REST API that delegates authorization decisions to the authz service.
+
+### SAML, OIDC, OAuth
+
+This experiment showcases how a separate authx service can handle both authentication and authorization using standard protocols:
+
+* SAML & OIDC for authentication
+* OAuth for authorization
+
+Actors in this experiment:
+
+* Authx service: Acts as a SAML Identity Provider and an OAuth Authorization Server.
+* API: A slimmed-down GitLab REST API.
+
+### API Gateway
+
+This experiment explores a stateless authorization mechanism by integrating a policy DSL (such as [Casbin][3]) into a reverse proxy.
+Authorization decisions are made early in the request pipeline based on HTTP request headers and body content.
+
+### Sidecar Process
+
+This experiment demonstrates a sidecar approach for making authorization decisions within an nginx process.
+Inspired by [Open Policy Agent][4] deployments. This experiment:
+
+* Uses lua bindings in nginx to connect to a local client process.
+* The client process proxies requests to a gRPC based policy decision service.
+
+
+[1]: https://gitlab.com/gitlab-org/gitlab/-/blob/e1f6db024561e35462ac8d9f54b8f9678f6ed6ee/app/models/ability.rb#L73
+[3]: https://casbin.org/
+[4]: https://www.openpolicyagent.org/