diff --git a/docs/ci.md b/docs/ci.md
index 150206f..a196a70 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -6,14 +6,34 @@ We'll document soon how to get onboarded (on request) on the CentOS CI infra pla
 We offer the following resources :
 
   * Openshift hosted jenkins (one per project/SIG), using usual authentication from FAS/ACO
-  * bare-metal and/or Virtual Machines ephemeral nodes on which you can run some tests (including destructive ones), that will be automatically be reinstalled (for bare-metal) or discarded (for VMs)
+  * bare-metal and/or Virtual Machines ephemeral nodes on which you can run some tests (including destructive ones), that will be automatically be reinstalled (for bare-metal) or discarded (for VMs) - aka `Duffy` 
 
 
-## Using bare-metal/Virtual Machines with Duffy client
+## Openshift
+
+
+
+## Duffy (ephemeral bare-metal/Virtual Machines provider)
+
 Duffy is the middle layer running ci.centos.org that manages the provisioning, maintenance and teardown / rebuild of the Nodes (physical hardware and VMs) that are used to run the tests in the CI Cluster.
 
+We provide both bare-metal and VMs and support the following architectures :
+
+  * x86_64 (both physical and VMs)
+  * aarch64 (both physical and VMs)
+  * ppc64le (only VMs on Power 8 or Power 9 but supporting nested virtualization)
+
+To be able to request ephemeral nodes to run your tests, you'll need both your `project` name and `api key` that will be generated for you once your project will have be allowed on that Infra.
+
+!!! note
+    It's worth knowing that there are quotas in place to ensure that you can't request infinite number of nodes in parallel and each `session` has a maximum lifetime of 6h. After that your nodes are automatically reclaimed by Duffy and are freshly reinstalled and put back in the Ready pool.
+
+!!! warning
+    The following notes are only applicable for new Duffy v3 API that will be available around August 2023. Previous `cico client` will continue to work on actual Duffy v2 instance for the time being
+
+
 ### Installing and configuring duffy client
-Use `pip` to install duffy client.
+Use `pip` (or `pip3.8` on el8) to install duffy client.
 
 ```shell
 pip install --user duffy[client]
@@ -71,6 +91,9 @@ By default this command outputs a _json_, but it's possible to change the format
 ```
 
 ### Retiring a session
+
+At the end of the test, you should "return" your ephemeral nodes to Duffy API service. This will trigger either a reinstall of the physical node (through kickstart) or just discarding/terminating it (if that's a cloud instance)
+
 To retire a session, the session id is required. Check the id executing.
 
 ```shell