diff --git a/site/docs/administrate/02-organisations.en.md b/site/docs/administrate/02-organisations.en.md
index f569b57b3..8ead0848b 100644
--- a/site/docs/administrate/02-organisations.en.md
+++ b/site/docs/administrate/02-organisations.en.md
@@ -37,28 +37,76 @@ An organisation can have multiple domain names, but only one of it can be primar
Browse to your [organisation](administrate#Organisations) by visiting [https://console.zitadel.ch/org](https://console.zitadel.ch/org).
Add the domain to your [organisation](administrate#Organisations) by clicking the button **Add Domain**.
-
+
+
> Do not delete the verification code **ZITADEL** will recheck the ownership from time to time
When the verification is successful you have the option to activate the domain by clicking **Set as primary**
-
+
+
> This changes the **preferred loginnames** of your [users](administrate#Users) as indicated [here](administrate#How_ZITADEL_handles_usernames).
Gratulations your are done! You can check this by visiting [https://console.zitadel.ch/users/me](https://console.zitadel.ch/users/me)
-
+
+
> This only works when the [user](administrate#Users) is member of this [organisation](administrate#Organisations)
diff --git a/site/docs/administrate/03-projects.en.md b/site/docs/administrate/03-projects.en.md
index 3e2d4fe7f..9fc9d0b38 100644
--- a/site/docs/administrate/03-projects.en.md
+++ b/site/docs/administrate/03-projects.en.md
@@ -42,11 +42,25 @@ To make it more easily to differentiate ZITADEL Console displays these both as s
To create your project go to [https://console.zitadel.ch/projects](https://console.zitadel.ch/projects)
-
+
#### RBAC Settings
diff --git a/site/docs/administrate/04-clients.en.md b/site/docs/administrate/04-clients.en.md
index cf23d639e..78d4632ae 100644
--- a/site/docs/administrate/04-clients.en.md
+++ b/site/docs/administrate/04-clients.en.md
@@ -24,18 +24,51 @@ The wizard can be skipped for people who are needing special settings.
To create a new client start by browsing to your [project](administrate#Projects), this is normally something like [https://console.zitadel.ch/projects/78562301657017889](https://console.zitadel.ch/projects/78562301657017889)
-
+
\ No newline at end of file
diff --git a/site/docs/administrate/06-users.en.md b/site/docs/administrate/06-users.en.md
index 9f7395279..0663545ad 100644
--- a/site/docs/administrate/06-users.en.md
+++ b/site/docs/administrate/06-users.en.md
@@ -29,21 +29,49 @@ If someone verifies a domain name within the organisation **ZITADEL** will gener
#### Search Users
-
+
Image 4: User Create Done
diff --git a/site/docs/develop/00-overview.en.md b/site/docs/develop/00-overview.en.md
index 6f01d34b2..c34397971 100644
--- a/site/docs/develop/00-overview.en.md
+++ b/site/docs/develop/00-overview.en.md
@@ -7,6 +7,8 @@ description: …
### APIs
+---
+
ZITADEL provides three API's for different use cases. These API's are built with GRPC and then generate a REST service.
Each services proto definition is located in the source control on GitHub.
As we generate the REST services and Swagger file out of the proto definition we recommend that you rely on the proto file.
@@ -27,6 +29,8 @@ See below for an example with the call **GetMyUser**.
}
```
+---
+
As you can see the `GetMyUser` function is also available as REST service under the path `/users/me`.
In the table below you can see the URI of those calls.
diff --git a/site/docs/documentation/03-openidoauth.en.md b/site/docs/documentation/03-openidoauth.en.md
index e24477bdf..efa1a5c85 100644
--- a/site/docs/documentation/03-openidoauth.en.md
+++ b/site/docs/documentation/03-openidoauth.en.md
@@ -18,7 +18,7 @@ Under normal circumstances **ZITADEL** need four domain names to operate properl
#### OpenID Connect 1.0 Discovery
The OpenID Connect Discovery Endpoint is located with the issuer domain.
-For example with [zitadel.ch](zitadel.ch) this would be the domain [issuer.zitadel.ch](issuer.zitadel.ch). This would give us [https://issuer.zitadel.ch/.well-known/openid-configuration](https://issuer.zitadel.ch/.well-known/openid-configuration).
+For example with [zitadel.ch](https://zitadel.ch) this would be the domain [issuer.zitadel.ch](https://issuer.zitadel.ch). This would give us [https://issuer.zitadel.ch/.well-known/openid-configuration](https://issuer.zitadel.ch/.well-known/openid-configuration).
**Link to spec.** [OpenID Connect Discovery 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-discovery-1_0.html)
diff --git a/site/docs/integrate/01-openidoauth.en.md b/site/docs/integrate/01-openidoauth.en.md
index cc91a2254..48b251762 100644
--- a/site/docs/integrate/01-openidoauth.en.md
+++ b/site/docs/integrate/01-openidoauth.en.md
@@ -23,6 +23,8 @@ In the OIDC and OAuth world this client profile is called "native application"
### How to consume authorizations in your application or service
+---
+
With ZITADEL you can manage the [roles](administrate#Roles) a [project](administrate#Projects) supplies to your users in the form of authorizations.
On the [project](administrate#Projects) it can be configured how **project roles** are supplied to the [clients](administrate#Clients).
By default ZITADEL asserts the claim **urn:zitadel:iam:org:project:roles** to the [Userinfo Endpoint](documentation#userinfo_endpoint)
@@ -39,4 +41,6 @@ By default ZITADEL asserts the claim **urn:zitadel:iam:org:project:roles** to th
}
```
+---
+
For more details about how **ZITADEL** treats [scopes](documentation#Scopes) and [claims](documentation#Claims) see the [documentations](documentation).
diff --git a/site/docs/start/00-quick-start.en.md b/site/docs/start/00-quick-start.en.md
index 3ca8c2c7c..855f25f81 100644
--- a/site/docs/start/00-quick-start.en.md
+++ b/site/docs/start/00-quick-start.en.md
@@ -14,7 +14,14 @@ You can either use [ZITADEL.ch](https://zitadel.ch) or deploy a dedicated **ZITA
To register your free [organisation](administrate#Organisations), visit this link [register organisation](https://accounts.zitadel.ch/register/org).
After accepting the TOS and filling out all the required fields you will receive a email with further instructions.
-
+