diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bc4ea93..71bb229 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,8 +14,11 @@ cd pr-af
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
+# Install the af CLI (control plane) once if you don't have it:
+curl -fsSL https://agentfield.ai/install.sh | bash
+
 cp .env.example .env       # set OPENROUTER_API_KEY and GH_TOKEN at minimum
-af                         # start the AgentField control plane in another terminal
+af server                  # start the AgentField control plane in another terminal
 python main.py             # start PR-AF
 ```
 
@@ -29,6 +32,8 @@ make clean         # remove caches and build artifacts
 
 CI runs ruff against `src/` and `scripts/` and validates the Docker build on every push. The test suite runs locally via `make test` (not in CI yet — see the issue tracker if you want to help wire it up). PRs that fail CI will not be merged until green.
 
+> **Known pre-existing test failure:** `tests/test_cost_tracker.py::TestCostTracker::test_async_log_success` currently fails on `main` (the cost tracker doesn't observe a stub response payload). Skip it locally with `make test` followed by `--deselect tests/test_cost_tracker.py::TestCostTracker::test_async_log_success` until it's fixed; CI is unaffected because pytest doesn't run there.
+
 ## What makes a good PR
 
 - **One concern per PR.** A bug fix and a refactor should be two PRs.
diff --git a/Makefile b/Makefile
index 46fa497..4d2209b 100644
--- a/Makefile
+++ b/Makefile
@@ -2,8 +2,9 @@ PYTHON ?= python3
 
 .PHONY: test check lint clean
 
+# PYTHONPATH=src so `from pr_af import ...` works without pip install -e .
 test:
-	$(PYTHON) -m pytest tests/ -x -q
+	PYTHONPATH=src $(PYTHON) -m pytest tests/ -x -q
 
 lint:
 	$(PYTHON) -m ruff check src/ scripts/
diff --git a/README.md b/README.md
index e85be88..4ccbf26 100644
--- a/README.md
+++ b/README.md
@@ -186,11 +186,11 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
 cp .env.example .env          # OPENROUTER_API_KEY, GH_TOKEN at minimum
-af                            # start AgentField control plane (terminal 1)
+af server                     # start AgentField control plane (terminal 1)
 python main.py                # start PR-AF on port 8004 (terminal 2)
 ```
 
-`af` ships with the `agentfield` package; if you don't have it on `PATH`, `python -m agentfield server` does the same thing. See [CONTRIBUTING.md](CONTRIBUTING.md) for the test/lint workflow.
+The `af` CLI is the AgentField control plane and ships separately from the Python SDK — install it once with `curl -fsSL https://agentfield.ai/install.sh | bash` if you don't have it on `PATH`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the test/lint workflow.
 
 ## Configuration
 
@@ -276,7 +276,7 @@ jobs:
 
 **Review hits the cost or duration cap.** The defaults (300s, $2) are tuned for smoke tests, not real reviews. Set `PR_AF_NO_BUDGET=true` (or raise `PR_AF_MAX_DURATION_SECONDS` to 1800+ and `PR_AF_MAX_COST_USD` to a real ceiling). The early termination is intentional — PR-AF posts whatever findings it has and notes the partial coverage in the summary.
 
-**`agent registered` never appears.** Check that the AgentField control plane is reachable (`curl http://localhost:8080/health` or `http://control-plane:8080/health` from inside the compose network) and that `AGENTFIELD_SERVER` matches. With `dev_mode=True` (the default), PR-AF retries registration on a 30s loop.
+**`Agent pr-af registered with DID system` never appears.** Check that the AgentField control plane is reachable (`curl http://localhost:8080/health` from the host, or `curl http://agentfield:8080/health` from inside the compose network) and that `AGENTFIELD_SERVER` matches the address PR-AF can actually reach. The agent doesn't poll on its own — if the first registration attempt fails, restart the PR-AF service after the control plane is up.
 
 **GitHub returns 403 / rate limit.** The default `GH_TOKEN` flow uses a fine-grained PAT. For higher rate limits and per-repo install scopes, switch to the GitHub App auth path with `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`.