diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f3b71c5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# API collections
+
+This is the repository where most frequent HTTP requests are stored as Bruno collections.
+
+## Requisites
+
+A Windows-based OS with Powershell version >= 7.5.x
+
+One or more of:
+
+- Bruno desktop client (<https://www.usebruno.com/>)
+- VSCode (<https://code.visualstudio.com/>) with httpyac extension (<https://marketplace.visualstudio.com/items?itemName=anweber.vscode-httpyac>)
+
+## Preparation
+
+After having cloned the repository, move in the root folder and follow these steps:
+
+1. launch `setup-tools.bat`: this will check the current Powershell environment and try to install required modules
+2. launch `setup-json-environment.bat`: follow the instrucions to generate a base environment file starting form the structure defined in the `env.json.template` file; at the end of the process you should have a `env.json` file in the root folder containing base values and secrets
+
+### Bruno collections
+
+If you have Bruno installed and intend to use it as the main tool, also do the following:
+
+1. launch `update-bruno-environments.bat`: the script will generate an environment file named `.env` in each one of the Bruno collection folders, using the base environment generated in the previous step; this minimizes the manual intervention needed to insert secrets in those collections
+2. launch Bruno and open the base collection folder named `bruno`.
+
+### httpyac requests
+
+If you want to use VSCode with httpyac extension, also do the following:
+
+1. launch `generate-httpyac-requests.bat`: the script will create an `autodocs/httpyac` folder in the root of the project containing the same Bruno requests in a standard HTTP format which can be read by VSCode and/or httpyac extension
+2. launch `update-httpyac-environments.bat`: the script will generate an environment file named `.env` in each one of the generated folders, using the base environment generated in the previous step
+3. launch VSCode and open the base project folder: with the explorer navigate to the `autodocs/httpyac` folder and browse to the request you want to use
+
+## Development
+
+**The main development tool to be used to manage API requests is Bruno.**
+
+The autodocs folder and its subfolder is (and must be) excluded from versioning: if you need to persist updates of any kind, this must be done through Bruno, because modifications to anything under autodocs will be ignored.
+
+### Secrets management
+
+Be careful to not save secret values in Bruno requests or anywhere else!
+
+To make secret management easier in Bruno, in each collection there is an environment file called `.env.template`: this file contains the Bruno variables whose values must not be versioned with an empty value.
+
+**Note**: it's strongly suggested to use the `update-*-environments.bat` scripts to automatically generate the local environment files.
+
+If you want to proceed manually, you should just copy-paste the template file to a new `.env` file and insert the appropriate secret values; this works because only the `.env.template` file is versioned, while all other `.env*` files are excluded.