diff --git a/README.md b/README.md
index 8f0f65f..18f34bb 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,62 @@
 
 [Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
 
+## CRM Backend Runbook
+
+### Environment
+
+- **Env file**: `/opt/crm/.env`
+- **Backend path**: `/opt/crm/backend`
+
+### Database / Prisma
+
+```bash
+# run migrations
+npx prisma migrate deploy
+
+# generate client
+npx prisma generate
+```
+
+### Seed demo data
+
+```bash
+# uses DATABASE_URL from /opt/crm/.env
+bash -lc 'set -a; . /opt/crm/.env; set +a; npx ts-node prisma/seed.ts'
+```
+
+### Build + restart (PM2)
+
+```bash
+npm run build
+pm2 restart crm-backend
+```
+
+### Smoke test
+
+```bash
+./test-api.sh
+```
+
+### Automated smoke (recommended)
+
+```bash
+/opt/crm/scripts/smoke_backend.sh
+
+# optionally reseed demo data
+/opt/crm/scripts/smoke_backend.sh --seed
+```
+
+### Tests
+
+```bash
+# runs e2e tests under ./test
+npm test
+
+# explicit e2e
+npm run test:e2e
+```
+
 ## Project setup
 
 ```bash
diff --git a/test-api.sh b/test-api.sh
index e1e2daf..5fbf562 100755
--- a/test-api.sh
+++ b/test-api.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-BASE_URL="http://127.0.0.1:3000"
+BASE_URL="${BASE_URL:-http://127.0.0.1:3000}"
 ACCESS_TOKEN=""
 REFRESH_TOKEN=""