From 8dfa9299ae7745047fe23b974112eea8f122cb3c Mon Sep 17 00:00:00 2001
From: Benjamin Labrecque <labrecque.benji@gmail.com>
Date: Fri, 17 Jul 2026 10:58:03 +0200
Subject: [PATCH] docs: add notes about environments to readme

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9cf9a0a..6c05bdb 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,60 @@
 # SLS HLA Framework
 
+## Environments
+
+The services are deployed to 2 environments:
+
+- `prod`
+    - network: `machine`
+    - host: `sls-vserv-bd-hla01`
+        - path: `/sls/bd/hla/prod/`
+- `dev`
+    - network: `office`
+    - host: `sls-vserv-bd-hla01-dev`
+        - path: `/sls/bd/hla/dev/`
+
+### Process Variables (PVs)
+
+We distinguish between 
+
+- `prod` and `dev` PVs 
+- **services specific** PVs from a dedicated IOC, and **external** PVs from other IOCs
+
+#### PVs - Service Specific 
+
+You create them, see (# TODO: docs...)
+
+`prod` and `dev` PVs automatically get created.
+
+In your code, you only use the `prod` name of a PV. The framework will automatically use the 
+`dev` name/PV when a service runs in the `dev` environment.
+
+#### PVs - External
+
+You can only access them. The framework will use the same PV in `prod` and `dev`, 
+i.e. there is no `dev` PV.
+
+#### PVs - Examples
+
+|  Environment | Service Specific | External |
+|---|---|---|
+|`prod` | `PV("AGEBD-MYSERVICE:MYPVNAME")`      | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` |
+| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")`  | - |
+
+### Python 
+
+For python services there are 3 environments. The python environment is set through the env variable `AGEBD_ENV`.
+
+- `prod`:  used when deployed to `prod`
+    - PVs: uses `prod` PVs
+    - `AGEBD_ENV=prod`
+- `dev`:   used when deployed to `dev`
+    - PVs: uses `dev` PVs
+    - `AGEBD_ENV=dev`
+- `local`: used when running code locally 
+    - PVs: uses fake/mock python objects as PVs, no access to real PVs
+    - `AGEBD_ENV=local`
+
 ## Hosts overview
 
 Check which network a host lives in, e.g. for `sls-lca`:
@@ -7,13 +62,13 @@ Check which network a host lives in, e.g. for `sls-lca`:
 ping sls-lca.psi.ch
 ```
 
-### Machine Net (PROD) 
+### Machine Net (`prod`) 
 
 - sls-lca
 - sls-vserv-bd-01
 - sls-vserv-bd-hla01
 
-### Office Net (DEV) 
+### Office Net (`dev`) 
 
 - sls-lc8
 - sls-lc9