diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80580f5..beef6fe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,6 +31,11 @@ core) with back-to-back builds deduped: starting `dev:server` and `dev:web` at t
 time (or just `pnpm dev`) installs and builds exactly once. `dev:docs` / `dev:landing`
 run the install check only (`--install-only`).
 
+Dev entry points that touch data (`pnpm dev`, `pnpm dev:server`, `pnpm penguin`) default
+to a separate data root, `~/.penguin/dev-data`, kept apart from the installed CLI/server's
+`~/.penguin/data` — hacking on the repo never mixes state with your real agents. Export
+`PENGUIN_HOME` to point them anywhere else; an explicit value always wins.
+
 Copy `.env.example` to `.env` for model credentials in development.
 
 ## Repo layout
diff --git a/package.json b/package.json
index d0ccfa0..c88f180 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
     "test:e2e": "pnpm --filter @prismshadow/penguin-core test:e2e",
     "build": "pnpm -r build && pnpm link:cli",
     "link:cli": "pnpm --dir packages/cli link --global || echo '[link:cli] pnpm global directory not configured; skipping the global penguin link (run pnpm setup once first)'",
-    "penguin": "tsx packages/cli/src/index.ts",
+    "penguin": "PENGUIN_HOME=\"${PENGUIN_HOME:-$HOME/.penguin/dev-data}\" tsx packages/cli/src/index.ts",
     "dev": "concurrently -n server,web -c cyan,magenta \"pnpm dev:server\" \"pnpm dev:web\"",
     "dev:server": "pnpm --filter @prismshadow/penguin-server dev",
     "dev:web": "node scripts/dev-prebuild.mjs && pnpm --filter @prismshadow/penguin-web dev",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 0dcc07f..8dfd65a 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -19,7 +19,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
     "build": "tsup",
-    "penguin": "tsx src/index.ts"
+    "penguin": "PENGUIN_HOME=\"${PENGUIN_HOME:-$HOME/.penguin/dev-data}\" tsx src/index.ts"
   },
   "dependencies": {
     "@prismshadow/agenthub": "^0.4.1",
diff --git a/packages/docs/content/installation.en.md b/packages/docs/content/installation.en.md
index 390519b..218e12f 100644
--- a/packages/docs/content/installation.en.md
+++ b/packages/docs/content/installation.en.md
@@ -60,7 +60,7 @@ cd penguin-harness
 pnpm install && pnpm build
 ```
 
-After the build, run `pnpm penguin <args>` inside the repo as the dev runner, or use the globally linked `penguin` command.
+After the build, run `pnpm penguin <args>` inside the repo as the dev runner, or use the globally linked `penguin` command. Dev entry points (`pnpm penguin`, `pnpm dev`) default to a separate data root `~/.penguin/dev-data`, while the linked/installed `penguin` keeps `~/.penguin/data`; export `PENGUIN_HOME` to override.
 
 ## Published npm packages
 
diff --git a/packages/docs/content/installation.zh.md b/packages/docs/content/installation.zh.md
index c48c003..51d51d7 100644
--- a/packages/docs/content/installation.zh.md
+++ b/packages/docs/content/installation.zh.md
@@ -60,7 +60,7 @@ cd penguin-harness
 pnpm install && pnpm build
 ```
 
-构建完成后，在仓库内用 `pnpm penguin <args>` 作为开发入口运行，或使用全局链接的 `penguin` 命令。
+构建完成后，在仓库内用 `pnpm penguin <args>` 作为开发入口运行，或使用全局链接的 `penguin` 命令。开发入口（`pnpm penguin`、`pnpm dev`）默认使用独立数据根目录 `~/.penguin/dev-data`，全局链接或安装的 `penguin` 仍使用 `~/.penguin/data`；可通过环境变量 `PENGUIN_HOME` 覆盖。
 
 ## 已发布的 npm 包
 
diff --git a/packages/server/package.json b/packages/server/package.json
index b495bc3..585ff6c 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -25,7 +25,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "dev": "node ../../scripts/dev-prebuild.mjs && tsx watch src/index.ts",
+    "dev": "node ../../scripts/dev-prebuild.mjs && PENGUIN_HOME=\"${PENGUIN_HOME:-$HOME/.penguin/dev-data}\" tsx watch src/index.ts",
     "start": "node --disable-warning=ExperimentalWarning dist/index.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",