diff --git a/README.md b/README.md
index dcd9e1b1..426b04c7 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,25 @@
 # Stack Orchestrator
 
-Stack Orchestrator allows building and deployment of a Laconic stack on a single machine.
+Stack Orchestrator allows building and deployment of a Laconic stack on a single machine with minimial prerequisites.
 
 ## Setup
 ### Developer Mode
 Developer mode runs the orchestrator from a cloned git repository.
 #### Prerequisites
-1. Python3
-1. Docker
+Stack Orchestrator is a Python3 CLI tool that runs on any OS with Python3 and Docker. Tested on: Ubuntu 20/22.
+
+Ensure that the following are already installed:
+
+1. Python3 (the version 3.8 available in Ubuntu 20/22 works)
+   ```
+   $ python3 --version
+   Python 3.8.10
+   ```
+1. Docker (Install a current version from dockerco, don't use the version from any Linux distro)
+   ```
+   $ docker --version
+   Docker version 20.10.17, build 100c701
+   ```
 #### Install
 1. Clone this repository:
    ```
@@ -52,21 +64,31 @@ _write-me_
 There are three sub-commands: `setup-repositories`, `build-containers` and `deploy-system` that are generally run in order:
 ### Setup Repositories
 Clones the set of git repositories necessary to build a system.
+
+Note: the use of `ssh-agent` is recommended in order to avoid entering your ssh key passphrase for each repository.
 ```
 $ laconic-so --verbose setup-repositories
 ```
 ### Build Containers
-Builds the set of docker container images required to run a system.
+Builds the set of docker container images required to run a system. It takes around 10 minutes to build all the containers from cold.
 ```
 $ laconic-so --verbose build-containers
 ```
 ### Deploy System
 Uses `docker compose` to deploy a system.
+
+Use `---include <list of components>` to deploy a subset of all containers:
 ```
 $ laconic-so --verbose deploy-system --include db-sharding,contract,ipld-eth-server,go-ethereum-foundry up
 ```
+```
+$ laconic-so --verbose deploy-system --include db-sharding,contract,ipld-eth-server,go-ethereum-foundry down
+```
 ## Implementation
-
+The orchestrator's operation is driven by files shown below. `repository-list.txt` container the list of git repositories; `container-image-list.txt` contains
+the list of container image names, while `clister-list.txt` specifies the set of compose components (corresponding to individual docker-compose-xxx.yml files which may in turn specify more than one container).
+Files required to build each container image are stored under `./container-build/<container-name>`
+Files required at deploy-time are stored under `./config/<component-name>`
 ```
 ├── cluster-list.txt
 ├── compose