diff --git a/README.md b/README.md
index 4849b2e..521a321 100644
--- a/README.md
+++ b/README.md
@@ -35,14 +35,25 @@ External comms are only possible from `approved`/`drafting` states, and only wit
 ## Quick start (POC)
 
 ```bash
-cp .env.example .env   # add LLM provider keys
-docker compose up -d postgres
-cd apps/api && uv venv .venv && . .venv/bin/activate && uv pip install -e .
-pytest                 # backend tests
-uvicorn app.main:app --reload
-cd apps/web && npm install && npm run dev
+cp .env.example .env   # add LLM provider keys (no key = mock mode, deterministic)
+
+# Backend tests + live API (DinD-safe: everything runs inside the compose network)
+docker compose run --rm api-test                                    # 47 pytest tests
+docker rm -f jobhunt-api-poc 2>/dev/null; \
+docker compose run -d --name jobhunt-api-poc \
+  --entrypoint "uvicorn app.main:app --host 0.0.0.0 --port 8000" api-test
+docker exec jobhunt-api-poc curl -s localhost:8000/api/health       # {"status":"ok"}
+
+# Frontend (host): Vue dev server proxies to the API
+cd apps/web && npm install && VITE_API_BASE=http://localhost:8000/api npm run dev
+
+# Packages (host, no DB needed): artifacts + llm-gateway unit tests
+cd packages/artifacts && uv venv && . .venv/bin/activate && uv pip install -e ".[dev]" && pytest -q
+cd packages/llm-gateway && uv venv && . .venv/bin/activate && uv pip install -e ".[dev]" && pytest -q
 ```
 
+Note: in sandboxed Docker-in-Docker environments host port publishing may not work; run curl/docker exec against the `jobhunt-api-poc` container directly, as above.
+
 ## Status
 
 POC scaffolding in progress. See `docs/` for the design.