diff --git a/README.md b/README.md
index e793a8ef9..1d38af30b 100644
--- a/README.md
+++ b/README.md
@@ -7,27 +7,6 @@
The Operator to install and manage the lifecycle of the [Kuadrant](https://github.com/Kuadrant/) components deployments.
-
-- [Overview](#overview)
-- [Architecture](#architecture)
- - [Kuadrant components](#kuadrant-components)
- - [Provided APIs](#provided-apis)
-- [Getting started](#getting-started)
- - [Pre-requisites](#pre-requisites)
- - [Installing Kuadrant](#installing-kuadrant)
- - [1. Install the Kuadrant Operator](#1-install-the-kuadrant-operator)
- - [2. Request a Kuadrant instance](#2-request-a-kuadrant-instance)
- - [Protect your service](#protect-your-service)
- - [If you are an *API Provider*](#if-you-are-an-api-provider)
- - [If you are a *Cluster Operator*](#if-you-are-a-cluster-operator)
-- [User guides](#user-guides)
-- [Kuadrant Rate Limiting](#kuadrant-rate-limiting)
-- [Documentation](#documentation)
-- [Contributing](#contributing)
-- [Licensing](#licensing)
-
-
-
## Overview
Kuadrant is a re-architecture of API Management using Cloud Native concepts and separating the components to be less coupled,
@@ -75,7 +54,7 @@ Additionally, Kuadrant provides the following CRDs
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [Kuadrant CRD](https://github.com/Kuadrant/kuadrant-operator/blob/main/api/v1beta1/kuadrant_types.go) | [Kuadrant Operator](https://github.com/Kuadrant/kuadrant-operator) | Represents an instance of kuadrant | [Kuadrant CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/config/samples/kuadrant_v1beta1_kuadrant.yaml) |
| [Limitador CRD](https://github.com/Kuadrant/limitador-operator/blob/main/api/v1alpha1/limitador_types.go) | [Limitador Operator](https://github.com/Kuadrant/limitador-operator) | Represents an instance of Limitador | [Limitador CR](https://github.com/Kuadrant/limitador-operator/blob/main/config/samples/limitador_v1alpha1_limitador.yaml) |
-| [Authorino CRD](https://github.com/Kuadrant/authorino-operator#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) |
+| [Authorino CRD](https://docs.kuadrant.io/authorino-operator/#the-authorino-custom-resource-definition-crd) | [Authorino Operator](https://github.com/Kuadrant/authorino-operator) | Represents an instance of Authorino | [Authorino CR](https://github.com/Kuadrant/authorino-operator/blob/main/config/samples/authorino-operator_v1beta1_authorino.yaml) |
diff --git a/doc/development.md b/doc/development.md
index fa0994d7a..acd960afe 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -1,26 +1,5 @@
# Development Guide
-
- * [Technology stack required for development](#technology-stack-required-for-development)
- * [Build](#build)
- * [Run locally](#run-locally)
- * [Deploy the operator in a deployment object](#deploy-the-operator-in-a-deployment-object)
- * [Deploy kuadrant operator using OLM](#deploy-kuadrant-operator-using-olm)
- * [Build custom OLM catalog](#build-custom-olm-catalog)
- * [Build kuadrant operator bundle image](#build-kuadrant-operator-bundle-image)
- * [Build custom catalog](#build-custom-catalog)
- * [Cleaning up](#cleaning-up)
- * [Run tests](#run-tests)
- * [Unit tests](#unittests)
- * [Integration tests](#integration-tests)
- * [All tests](#all-tests)
- * [Lint tests](#lint-tests)
- * [(Un)Install Kuadrant CRDs](#uninstall-kuadrant-crds)
-
-
-
-
-
## Technology stack required for development
* [operator-sdk] version v1.28.1
diff --git a/doc/user-guides/authenticated-rl-for-app-developers.md b/doc/user-guides/authenticated-rl-for-app-developers.md
index dda1c795d..e0e22b83f 100644
--- a/doc/user-guides/authenticated-rl-for-app-developers.md
+++ b/doc/user-guides/authenticated-rl-for-app-developers.md
@@ -2,15 +2,12 @@
This user guide walks you through an example of how to configure authenticated rate limiting for an application using Kuadrant.
-
-
Authenticated rate limiting rate limits the traffic directed to an application based on attributes of the client user, who is authenticated by some authentication method. A few examples of authenticated rate limiting use cases are:
+
- User A can send up to 50rps ("requests per second"), while User B can send up to 100rps.
- Each user can send up to 20rpm ("request per minute").
- Admin users (members of the 'admin' group) can send up to 100rps, while regular users (non-admins) can send up to 20rpm and no more than 5rps.
-
-
In this guide, we will rate limit a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request. The API exposes an endpoint at `GET http://api.toystore.com/toy`, to mimic an operation of reading toy records.
We will define 2 users of the API, which can send requests to the API at different rates, based on their user IDs. The authentication method used is **API key**.
@@ -20,8 +17,6 @@ We will define 2 users of the API, which can send requests to the API at differe
| alice | 5rp10s ("5 requests every 10 seconds") |
| bob | 2rp10s ("2 requests every 10 seconds") |
-
-
## Run the steps ① → ④
### ① Setup
@@ -225,8 +220,6 @@ EOF
> **Note:** It may take a couple of minutes for the RateLimitPolicy to be applied depending on your cluster.
-
-
Verify the rate limiting works by sending requests as Alice and Bob.
Up to 5 successful (`200 OK`) requests every 10 seconds allowed for Alice, then `429 Too Many Requests`:
diff --git a/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md b/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md
index 1393c822b..c4844c649 100644
--- a/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md
+++ b/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md
@@ -1,13 +1,12 @@
# Authenticated Rate Limiting with JWTs and Kubernetes RBAC
This user guide walks you through an example of how to use Kuadrant to protect an application with policies to enforce:
+
- authentication based OpenId Connect (OIDC) ID tokens (signed JWTs), issued by a Keycloak server;
- alternative authentication method by Kubernetes Service Account tokens;
- authorization delegated to Kubernetes RBAC system;
- rate limiting by user ID.
-
-
In this example, we will protect a sample REST API called **Toy Store**. In reality, this API is just an echo service that echoes back to the user whatever attributes it gets in the request.
The API listens to requests at the hostnames `*.toystore.com`, where it exposes the endpoints `GET /toy*`, `POST /admin/toy` and `DELETE /amind/toy`, respectively, to mimic operations of reading, creating, and deleting toy records.
@@ -266,14 +265,14 @@ subjects:
EOF
```
-
+
Q: Can I use Roles and RoleBindings instead of ClusterRoles and ClusterRoleBindings?
Yes, you can.
The example above is for non-resource URL Kubernetes roles. For using `Roles` and `RoleBindings` instead of
`ClusterRoles` and `ClusterRoleBindings`, thus more flexible resource-based permissions to protect the API,
- see the spec for [Kubernetes SubjectAccessReview authorization](https://github.com/Kuadrant/authorino/blob/v0.5.0/docs/features.md#kubernetes-subjectaccessreview-authorizationkubernetes)
+ see the spec for [Kubernetes SubjectAccessReview authorization](https://docs.kuadrant.io/authorino/docs/features/#kubernetes-subjectaccessreview-authorizationkubernetessubjectaccessreview)
in the Authorino docs.