diff --git a/README.md b/README.md
index e38cb1ba..c3d9fc8e 100644
--- a/README.md
+++ b/README.md
@@ -218,7 +218,8 @@ By default, agents run on scheduled heartbeats and event-based triggers (task as
 ## Development
 
 ```bash
-pnpm dev              # Full dev (API + UI)
+pnpm dev              # Full dev (API + UI, watch mode)
+pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 4659bb4b..bb287623 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -29,6 +29,8 @@ This starts:
 - API server: `http://localhost:3100`
 - UI: served by the API server in dev middleware mode (same origin as API)
 
+`pnpm dev` runs the server in watch mode and restarts on changes from workspace packages (including adapter packages). Use `pnpm dev:once` to run without file watching.
+
 Tailscale/private-auth dev mode:
 
 ```sh
diff --git a/package.json b/package.json
index ad6d692f..45c02b8b 100644
--- a/package.json
+++ b/package.json
@@ -3,8 +3,9 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "node scripts/dev-runner.mjs dev",
+    "dev": "node scripts/dev-runner.mjs watch",
     "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
+    "dev:once": "node scripts/dev-runner.mjs dev",
     "dev:server": "pnpm --filter @paperclipai/server dev",
     "dev:ui": "pnpm --filter @paperclipai/ui dev",
     "build": "pnpm -r build",