diff --git a/docs/pi-dev.md b/docs/pi-dev.md
index be95ead80cc..322bd13cd39 100644
--- a/docs/pi-dev.md
+++ b/docs/pi-dev.md
@@ -19,19 +19,25 @@ This guide summarizes a sane workflow for working on the pi integration in OpenC
 
 ## Running Pi Tests
 
-Use the dedicated script for the pi integration test set:
+Run the Pi-focused test set directly with Vitest:
 
 ```bash
-scripts/pi/run-tests.sh
+pnpm test -- \
+  "src/agents/pi-*.test.ts" \
+  "src/agents/pi-embedded-*.test.ts" \
+  "src/agents/pi-tools*.test.ts" \
+  "src/agents/pi-settings.test.ts" \
+  "src/agents/pi-tool-definition-adapter*.test.ts" \
+  "src/agents/pi-extensions/**/*.test.ts"
 ```
 
-To include the live test that exercises real provider behavior:
+To include the live provider exercise:
 
 ```bash
-scripts/pi/run-tests.sh --live
+OPENCLAW_LIVE_TEST=1 pnpm test -- src/agents/pi-embedded-runner-extraparams.live.test.ts
 ```
 
-The script runs all pi related unit tests via these globs:
+This covers the main Pi unit suites:
 
 - `src/agents/pi-*.test.ts`
 - `src/agents/pi-embedded-*.test.ts`