diff --git a/site/docs/administrate/02-organisations.en.md b/site/docs/administrate/02-organisations.en.md
index f569b57b31..8ead0848bb 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**.
-
+
+
+
Input the domain in the input field and click **Add**
-
-
-
-
+
+
+
+
To start the domain verification click the domain name and a dialog will appear, where you can choose between DNS or HTTP challenge methods.
-
+
+
+
For example, create a TXT record with your DNS provider for the used domain an click verify. **ZITADEL** will then proceed an check your DNS.
-
+
+
+
+
> 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 3e2d4fe7f1..9fc9d0b38f 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)
-
+
+
+
Create a new project with name which explains what's the intended use of this project.
-
+
+
+
#### RBAC Settings
diff --git a/site/docs/administrate/04-clients.en.md b/site/docs/administrate/04-clients.en.md
index cf23d639e5..78d4632aee 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)
-
+
+
+
Click the **New** button and a wizard will appear which will guide you through the process.
-
-
-
-
-
-
-
+
+
+
+
+
+
When the wizard is complete, the clients configuration will be displayed and you can now use this client.
-
\ No newline at end of file
+
+
+
\ 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 9f73952792..0663545ad1 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 1: User List Search
#### Create Users
-
+
+
+
Image 2: User List
-
+
+
+
Image 3: User Create Form
-
+
+
+
Image 4: User Create Done
diff --git a/site/docs/develop/00-overview.en.md b/site/docs/develop/00-overview.en.md
index 6f01d34b29..c343979711 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 e24477bdf1..efa1a5c855 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 cc91a22547..48b2517624 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 3ca8c2c7c5..855f25f81e 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.
-
+
+
+
#### Verify your domain name (optional)
diff --git a/site/docs/use/00-user.en.md b/site/docs/use/00-user.en.md
index a14d4ddf12..b4556372ce 100644
--- a/site/docs/use/00-user.en.md
+++ b/site/docs/use/00-user.en.md
@@ -22,14 +22,23 @@ title: User Manual
### Login User
-
-
-Image: Login Username
-
-
-
-Image: Login Password
-
-
-
-Image: Login OTP
+