fix(tooling): separate the dev data root from the installed one (#67)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

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

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",

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",

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
 

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 包
 

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",