diff --git a/tests/README.md b/tests/README.md
index efdab4b..4c6c30b 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -22,22 +22,56 @@ Inside the regtest container `fava` is already provisioned.
 
 ## Running
 
-From the LNbits source root (with the libra extension reachable via `LNBITS_EXTENSIONS_PATH` or symlinked into `lnbits/extensions/`):
+The suite targets the **`lnbits/dev` worktree** (`~/dev/lnbits/dev`) — it
+relies on dev-branch modules (`lnbits.core.signers`, the bunker work) that
+`main` doesn't carry. A known-good invocation from scratch:
 
 ```bash
-# Whole suite
-pytest path/to/libra/tests
+# One-time: build a venv with lnbits (dev) + test deps + fava
+nix-shell -p uv --run "uv venv /tmp/libra-test-venv --python 3.12 && \
+  uv pip install --python /tmp/libra-test-venv/bin/python \
+    -e ~/dev/lnbits/dev pytest asgi-lifespan fava"
 
+# Run (each invocation gets a fresh data folder — REQUIRED, see gotchas)
+cd ~/dev/lnbits/dev && \
+env LNBITS_KEY_MASTER=$(openssl rand -hex 32) \
+    LNBITS_DATA_FOLDER=$(mktemp -d -t libra-test-data-XXXX) \
+    LNBITS_EXTENSIONS_PATH=$HOME/dev/shared \
+    PYTHONPATH=$HOME/dev/shared/extensions:. \
+    PATH=/tmp/libra-test-venv/bin:$PATH \
+  /tmp/libra-test-venv/bin/pytest ~/dev/shared/extensions/libra/tests -q
+```
+
+```bash
 # Smoke test only (validate the harness before running everything)
-pytest path/to/libra/tests/test_smoke.py
+... pytest path/to/libra/tests/test_smoke.py
 
 # One area
-pytest path/to/libra/tests/test_balances_api.py
+... pytest path/to/libra/tests/test_balances_api.py
 
 # Single test, verbose
-pytest path/to/libra/tests/test_balances_api.py::test_mixed_income_expense_nets_correctly -v
+... pytest path/to/libra/tests/test_balances_api.py::test_mixed_income_expense_nets_correctly -v
 ```
 
+### Environment gotchas (each cost a failed run on 2026-06-12)
+
+- **`LNBITS_EXTENSIONS_PATH` is the *parent* of an `extensions/` dir** —
+  lnbits scans `{path}/extensions/` (`lnbits/app.py`,
+  `build_all_installed_extensions_list`). For extensions at
+  `~/dev/shared/extensions/libra`, pass `~/dev/shared`. Pointing it at
+  `~/dev/shared/extensions` makes libra invisible: zero extensions install,
+  migrations never run, and every test errors with
+  `no such table: extension_settings`.
+- **Set `LNBITS_DATA_FOLDER` to a fresh temp dir explicitly.** The
+  conftest's `os.environ.setdefault` redirect is not always effective;
+  reusing a previous run's database fails `first_install` with
+  "Username already exists" during app-fixture setup.
+- **`LNBITS_KEY_MASTER` (32-byte hex) is mandatory on lnbits dev** — the
+  signer migration aborts startup without it (issue lnbits#9
+  encrypt-at-rest). Any random value is fine for tests.
+- **lnbits `main` does not work**: extensions importing
+  `lnbits.core.signers` fail to load, and libra's app fixture errors.
+
 The Fava subprocess starts once per session (~1-2s) and is shared across tests; each test creates its own LNbits user so the shared ledger doesn't cause inter-test interference.
 
 ## Conventions