diff --git a/README.md b/README.md
index df45967..3deeeb2 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,40 @@
 # lumbunglib
 
-> Python lib which powers `lumbung[dot]space` automation
+> Python lib which powers `lumbung.space` automation
 
 ## hacking
 
-- run `poetry run poetry2setup > setup.py` if updating the poetry dependencies
-- if adding a new cli command, extend `pyproject.toml` with a new `[tool.poetry.scripts]` entry
+Install [poetry](https://python-poetry.org/docs/#osx--linux--bashonwindows-install-instructions):
+
+```bash
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+```
+
+We use Poetry because it locks the dependencies all the way down and makes it
+easier to manage installation & maintenance in the long-term. Then install the
+dependencies & have them managed by Poetry:
+
+```
+poetry install
+```
+
+Each script requires some environment variables to run, you can see the latest
+deployment configuration over
+[here](https://git.autonomic.zone/ruangrupa/lumbung.space/src/branch/main/compose.yml),
+look for the values under the `environment: ...` stanza.
+
+All scripts have an entrypoint described in the
+[`pypoetry.toml`](https://git.autonomic.zone/ruangrupa/lumbunglib/src/commit/40bf9416b8792c08683ad8ac878093c7ef1b2f5d/pyproject.toml#L27-L31)
+which you can run via `poetry run ...`. For example, if you want to run the
+[`lumbunglib/video.py`](./lumbunglib/video.py) script, you'd do:
+
+```
+mkdir -p testdir
+export OUTPUT_DIR=/testdir
+poetry run lumbunglib-vid
+```
+
+Run `poetry run poetry2setup > setup.py` if updating the poetry dependencies.
+This allows us to run `pip install .` in the deployment and Pip will understand
+that it is just a regular Python package. If adding a new cli command, extend
+`pyproject.toml` with a new `[tool.poetry.scripts]` entry.