diff --git a/AGENTS.md b/AGENTS.md
index 524c573abe0..89cefbef4be 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -108,6 +108,21 @@ Notes:
 
 ## 7. Verification Before Hand-off
 
+Default local/agent test path:
+
+```sh
+pnpm test
+```
+
+This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
+
+```sh
+pnpm test:e2e
+pnpm test:release-smoke
+```
+
+Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
+
 Run this full check before claiming done:
 
 ```sh
diff --git a/README.md b/README.md
index bff4b1c71a7..734c2fdba11 100644
--- a/README.md
+++ b/README.md
@@ -233,11 +233,15 @@ pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
-pnpm test:run         # Run tests
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```
 
+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
 See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 
 <br/>
diff --git a/cli/README.md b/cli/README.md
index 4de796b5d80..db92a539835 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -233,11 +233,15 @@ pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
-pnpm test:run         # Run tests
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```
 
+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
 See [doc/DEVELOPING.md](https://github.com/paperclipai/paperclip/blob/master/doc/DEVELOPING.md) for the full development guide.
 
 <br/>
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index f86ab47be82..df2b000220f 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -79,6 +79,29 @@ Allow additional private hostnames (for example custom Tailscale hostnames):
 pnpm paperclipai allowed-hostname dotta-macbook-pro
 ```
 
+## Test Commands
+
+Use the cheap local default unless you are specifically working on browser flows:
+
+```sh
+pnpm test
+```
+
+`pnpm test` runs the Vitest suite only. For interactive Vitest watch mode use:
+
+```sh
+pnpm test:watch
+```
+
+Browser suites stay separate:
+
+```sh
+pnpm test:e2e
+pnpm test:release-smoke
+```
+
+These browser suites are intended for targeted local verification and CI, not the default agent/human test command.
+
 ## One-Command Local Run
 
 For a first-time local install, you can bootstrap and run in one command:
diff --git a/package.json b/package.json
index 9ab8f60c87c..ea356f0b491 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,8 @@
     "dev:ui": "pnpm --filter @paperclipai/ui dev",
     "build": "pnpm run preflight:workspace-links && pnpm -r build",
     "typecheck": "pnpm run preflight:workspace-links && pnpm -r typecheck",
-    "test": "pnpm run preflight:workspace-links && vitest",
+    "test": "pnpm run test:run",
+    "test:watch": "pnpm run preflight:workspace-links && vitest",
     "test:run": "pnpm run preflight:workspace-links && vitest run",
     "db:generate": "pnpm --filter @paperclipai/db generate",
     "db:migrate": "pnpm --filter @paperclipai/db migrate",